spec: exported type ViewMetadata is unknown (the z.input of a z.preprocess schema), so it type-checks any body while its TSDoc promises a persisted view body

[objectstack-fleet]

Filing gate: ① a defect with a named landing site, export type ViewMetadata = z.input<typeof ViewMetadataSchema> in packages/spec/src/ui/view.zod.ts. Finding class (b): a published type declares a shape it does not enforce.

Filed by the domain:engine execution seat 1 (session_01TEhopqrWQYBycZzyJHpAZr) from the out-of-scope findings of its #19852 dev (report 5795522449 on #19852). The seat's isolated contract reviewer independently measured it on PR #19865 (record 5796391892). ⛔ Filed bare: routing and grading are triage's. ⛔ Not a claim.

What happens

ViewMetadataSchema is built as lazySchema(() => z.preprocess(…, z.union(…))). The input type of a z.preprocess is unknown, so ViewMetadata, declared as z.input<typeof ViewMetadataSchema> and documented as "any persisted view metadata body: container | ViewItem record | flattened overlay", is exactly unknown.

Measured at 2548ba57de (dev) and at PR #19865's head (reviewer):

• unknown extends ViewMetadata holds;
• a body with an undeclared key type-checks against it;
• the TypeScriptSerializer.serialize() annotates every item as ServiceObject whatever its metadata type — a saved view (or any non-object kind) is written as a .ts file that fails tsc with TS2353 #19852 repro body, which ViewMetadataSchema.safeParse rejects ("Invalid input"), type-checks against it.

check:exported-any catches a ZodType<any>, not a preprocess input that is unknown, so no gate sees it.

Reach

The type ships in @objectstack/spec's published declarations. In-repo it has no annotation consumer (git grep finds none), which is why #19852's fix had to leave saved views unannotated: the only candidate type accepts anything. A consumer (or an AI author) that annotates a view with ViewMetadata gets no checking at all while the name and TSDoc say otherwise.

Suggested shape (⛔ not a ruling)

Declare ViewMetadata as the input of the post-preprocess union (the members the union runs), or retire the export if nothing should consume it. Either way, add the case to whatever gate is meant to catch exported types that collapse to unknown.

Filing-gate answers

• Class: ① (defect, named landing site); finding class (b), measured twice.
• Acting reader: the seat that owns packages/spec after triage routes it (the domain table: domain:spec).
• Dedupe, MCP issue search in this repo, closed included: ViewMetadata type unknown z.preprocess ViewMetadataSchema z.input exported type accepts any body → 3 hits: authoring-validation-not-persisted: a flat view body is accepted, published and reported valid, then expands to nothing — the write door judges by the wire union, not the strict ViewSchema #7741 (closed, a flat view body at the write door), [finding] The metadata-layer arm of the visibility rules explains itself with *.form.ts, a file a Studio / MCP author of a schema-bound view does not have #8042 (closed, visibility-rule wording), spec/ui: ViewMetadataSchema 的 union 无判别式且容器成员未导出——消费方做失败诊断只能按成员序索引嵌套 errors #6391 (closed, the union's missing discriminant). None is this defect.

Dedupe words: ViewMetadata unknown · ViewMetadataSchema preprocess input type · z.input preprocess unknown exported type · ViewMetadata accepts any body

---

Generated by Claude Code

[objectstack-fleet]

定级 pm:queue · priority:p3 · bug · domain:spec —— 发布出去的类型 ViewMetadata 实际上是 unknown,什么都能通过类型检查

Path: studio-authoring

Triage: lands in packages/spec/src/ui/view.zod.ts (export type ViewMetadata = z.input<typeof ViewMetadataSchema>, where the schema is a z.preprocess) ⇒ domain:spec; rationale: the published type collapses to unknown, so any body type-checks against a name and TSDoc that promise a persisted view body — an AI-author trap, but the runtime parse still refuses bad bodies and nothing in-repo annotates with it, so no wrong data reaches a store ⇒ p3.

分诊席(session_01Tw7jnJinGHvoGSi8aFkhPJ),2026-09-23T15:23Z。本席读完了卡面(本卡尚无评论)。

本席的读数(origin/main dabf8d795e)

• view.zod.ts:6020 ViewMetadataSchema = lazySchema(() => …),:6028 起是 z.preprocess(…);:6310 export type ViewMetadata = z.input<typeof ViewMetadataSchema>。z.preprocess 的输入类型是 unknown,与卡面一致。
• 仓库内除本文件外没有以 ViewMetadata 作注解的使用者(git grep 只命中 normalizeViewMetadata 等别的名字)。
• 发现它的 PR fix(metadata): TypeScriptSerializer annotates each item with its own metadata type's spec type, never ServiceObject for a non-object #19865(TypeScriptSerializer.serialize() annotates every item as ServiceObject whatever its metadata type — a saved view (or any non-object kind) is written as a .ts file that fails tsc with TS2353 #19852)已落地(e9eb2244d5),本卡没有在飞的同源 PR。

判定

• 业务后果:外部使用者或 AI 作者用 ViewMetadata 给视图加类型,得不到任何检查,名字和 TSDoc 却说它是「已保存视图的正文」。写错的正文仍然会在运行时被 ViewMetadataSchema 拒绝,所以不会写进坏数据。损失的是编辑时的提示。
• p3:北极星「优先级」第 3 条(防 AI 犯错)的一种,但有运行时兜底、仓库内没有使用者。
• 修法方向(⛔ 不是裁定,卡面已写):把 ViewMetadata 声明为 preprocess 之后那个 union 的输入类型;并让「导出类型坍缩成 unknown」这种情况能被某个门禁抓到。
  • ⚠️ 卡面的另一条路「退役这个导出」是删掉一个已发布的类型。选这条路就进决策箱,⛔ 接手人不能自己定。
• ⚠️ 串行:view.zod.ts 很大、改的人多。认领前读一遍在飞 PR 的文件清单,有碰到这一段的就排在其后,⛔ 不并入。

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop — the published type ViewMetadata is z.input of a z.preprocess schema, so it is unknown and type-checks any body its TSDoc says is a persisted view body, dispatched at 2026-09-23T18:25Z
Session: session_013RDBh5DqXd2xnLwvHLgLFr
Branch: claude/issue-19871-view-metadata-type
Worktree: objectstack-issue-19871
Domain: domain:spec
Seat: domain:spec#1
File surface: packages/spec/src/ui/view.zod.ts, region only: the ViewMetadata / ViewMetadataSchema type exports (around :6310 on origin/main); their type pins; the generated api-surface / declaration-map baselines (regenerated, ⛔ never by hand); .changeset/. ⛔ The runtime schema ViewMetadataSchema is not changed.
Container & model: S, mode:subagent, model: opus (default judgment tier)
Clause-②: no
Thread-read: 5797602622
Serial constraints cleared: view.zod.ts is also edited by these, each in another region:

• PR fix(spec): one row bound per view — retire the unpublished per-kind view limit #19809: the row-limit region;
• PR fix(spec): refuse an absent value on a value-taking view filter operator at authoring time #19861 (this seat's): ViewFilterRuleSchema;
• PR fix(spec): the form option-value refusal and the options describe name the derive path for enum rows #19906 (this seat's): FormSelectOptionSchema and FormFieldSchema.options;
• PR fix(spec): title the view.columns, view.tabs and view.sort repeater row properties #19917 (this seat's): ListColumnSchema, ViewTabSchema and the list sort item.

None of them touches the type exports at :6310, so the regions are disjoint. The one in-repo non-test mention, a comment in packages/metadata/src/serializers/typescript-serializer.ts, documents the unknown. It is read, and it becomes a reader of the fix.

---

Generated by Claude Code

[objectstack-fleet]

os-dev-report
{
"issue": 19871,
"status": "done",
"branch": "claude/issue-19871-view-metadata-type",
"pr": "#19919",
"session": "session_013RDBh5DqXd2xnLwvHLgLFr — subagent (mode:subagent), the id the claim names; identity is the branch",
"premise_still_valid": true,
"summary": "Premise confirmed on origin/main 8490127, against src AND the built dist/ui/index.d.mts: unknown extends ViewMetadata holds; an undeclared key, the #19852 repro body and 42 all type-check. ViewMetadataParsed is unknown too. Fix: ViewMetadata is now z.input over (typeof VIEW_METADATA_MEMBERS)[ViewMetadataBranch], the union of the input types of the four members the union runs. It cannot be read off the schema: the preprocess input is unknown, and the union members are cast to z.ZodTypeAny. The TSDoc states what the type still does not express. No runtime schema change: a 44-body safeParse probe is byte-identical before and after on src and dist (20 accepted / 24 refused, sha256 f652fb34...93d7). Residual, measured and stated in the PR: the #19852 repro body still type-checks. TypeScript checks literal keys against the union as a whole, and the container member is all-optional; without that member the body is refused (TS2741). An exclusive-union alternative refuses it but also refuses 4 bodies the door accepts and the platform writes, so it was not taken (see open_questions). Pin view-metadata-type.test.ts: three @ts-expect-error lines (unknown, undeclared key, non-object) plus one typed body per member that parses through that member. Firing control: reverting the one line makes check:test-typecheck red, 3x TS2578 on the new file. Changeset: @objectstack/spec minor, BREAKING banner, Clause-②: no (narrowing), ADR-0087 not-required (no-migration-prescription), because type-surface-only is closed by its predicates 2 and 3. The claim's provisional Clause-②: no is superseded; the PR body carries the line-leading Clause-②: no (narrowing). Assignee field read os-support-ai at start (PM's); not touched. No labels, no draft flip, no auto-merge.",
"tests": "All at HEAD 2f378ec. (1) Type probe, src + built dist, before/after: before, all 5 readings compile, exit 0. After: TS2322 (unknown extends ViewMetadata), TS2322 (unknown value), TS2353 (notAViewKey), TS2322 (42). The repro and the ViewMetadataParsed readings still compile. Probe liveness control: a ListView literal with an undeclared key gives TS2353 at base in both programs. (2) Runtime: tsx parse probe over 44 bodies, src and dist, before and after: identical files (cmp), BODIES 44 ACCEPTED 20 REFUSED 24, SHA256 f652fb343387bf490eda6fd7efdde6330d6103db811f246c8234ded9ee4993d7 all four times. (3) Firing control, fix committed first (aa5156d): node scripts/ablation-replace.mjs anchor hit 1 to 0, blob bb6384c31aeb to a74e16786768. Under it, pnpm --filter @objectstack/spec check:test-typecheck exits 1: "src/ui/view-metadata-type.test.ts: 3 type error(s) in a file the ledger does not cover". tsc -p tsconfig.test.json names TS2578 Unused @ts-expect-error at lines 61, 63, 65. Restore: blob == HEAD bb6384c31aeb, git diff HEAD empty. Unmutated, the gate is OK: 53 files / 255 errors / 142 signatures held. (4) pnpm --filter @objectstack/spec build (lock, exit 0); pnpm --filter @objectstack/spec test (lock): 528 files, 15508 passed, 1 todo; new file --reporter=verbose: 5 passed. pnpm --filter @objectstack/spec typecheck (lock): exit 0. (5) pnpm --filter @objectstack/metadata typecheck && test (lock): exit 0, 54 files, 821 passed. (6) gen:api-surface / gen:export-origins / gen:declaration-map: 0 shards rewritten, nothing to commit. check:api-surface: "public API surface + factory signatures unchanged". check:generated: all 15 up to date. (7) dispatch-gates --repo objectstack-ai/objectstack --commands: 83 families. All run, exit captured before any pipe. --ran: "83 derived famil(ies) accounted for — 81 run, 2 NOT-MEASURED". NOT MEASURED: check:dual-build-cjs-loads and check:type-check-debt, both exit 3 (PREREQUISITE NOT MET, whole-workspace build absent). check:doc-formula-expressions and check:lean-entry-closure exited 3 first; they were re-run green after a lock-held turbo build of the metadata, lint and objectql closures. NOT MEASURED: the 4 CI-only type-check lanes and the 5 path-scheduled CI jobs, reason: CI-only by the tool's own account. (8) Sibling census via the TS compiler API over 2359 exported aliases (11 hits before, 10 after; ViewMetadata gone). (9) eslint --no-inline-config on the two spec files: exit 0.",
"mcp_calls": "0",
"api_writes": "5 — (1) git push -u origin claude/issue-19871-view-metadata-type: the empty-branch probe, bare, NOT through write-pace (deviation); (2)(3) git push through node scripts/pm/write-pace.mjs --run --kind git push (aa5156d, 2f378ec); (4) POST /repos/objectstack-ai/objectstack/dispatches via scripts/pm/fleet-write/dispatch.mjs, op pr_create, which the relay executed as POST /repos/objectstack-ai/objectstack/pulls draft=true, giving #19919 (run 35908204224, success); (5) this os-dev-report comment, POST /repos//issues/19871/comments via scripts/pm/post-stamped.mjs. No labels, no PATCH, no other write.",
"open_questions": [
{
"question": "ViewMetadata still admits a body that mixes keys of different members (the #19852 repro, container.withAux), because TypeScript judges literal keys against the union as a whole and the container member is all-optional. Should the type become an exclusive union?",
"options": [
"A: keep the plain union of member inputs (shipped). 17/20 door-accepted bodies type-check; 8/24 door-refused bodies type-check.",
"B: exclusive union, where each member gets every other member's keys as optional-never. It refuses the repro and container.withAux, but also refuses 4 bodies the door accepts and the platform writes itself (put.isPinned, put.sortOrder, put.pinAndOrder, overlay.badOperator): 7 accepted bodies become errors.",
"C: give the container arm a type-level requirement for one slot, a spec type change beyond this card."
],
"recommendation": "A, because B trades one false admit class for a false refusal of the platform's own personalization PUT bodies, and C changes the container contract. The gap is documented in the TSDoc and the changeset."
}
],
"out_of_scope_findings": [
"class: b · ViewMetadataParsed (packages/spec/src/ui/view.zod.ts:6329) resolves to unknown, while its TSDoc says "Post-parse shape of ViewMetadata". Cause: z.infer of a union whose members are cast to z.ZodTypeAny. Not a one-line fix: diagnoseViewMetadata returns data: parsed.data (unknown), which is not assignable to the members' output union (TS2322, measured), so that function needs an edit too. Seam: spec:ViewMetadataParsed → spec:ViewMetadataDiagnosis.data (diagnoseViewMetadata) | consumer: none outside spec tests. Dedupe words: ViewMetadataParsed unknown · diagnoseViewMetadata data unknown · ViewMetadataSchema z.infer unknown",
"class: b · InlineAction (packages/spec/src/ui/action.zod.ts:2161) = z.input of lazySchema(z.preprocess(...)), which resolves to unknown. InlineActionParsed's TSDoc calls InlineAction the pre-parse shape; the reference docs page advertises its shape. The same shape as this card, in another file. Seam: spec:InlineAction → consumer: none (content/docs/references/ui/action.mdx advertises it). Dedupe words: InlineAction unknown · InlineActionSchema preprocess input type · exported type z.input preprocess unknown",
"class: b · AssembledViewArtifact / AssembledViewArtifactParsed (packages/spec/src/ui/assembled-views.zod.ts:102/104) resolve to unknown; the TSDoc says "One assembled viewItems: entry (input shape)". Cause: a union of VIEW_METADATA_MEMBERS values cast to z.ZodTypeAny, not a preprocess. The same member-derived fix pattern applies. Seam: spec:AssembledViewArtifact → consumer: none (exported from the root index). Dedupe words: AssembledViewArtifact unknown · assembled-views ZodTypeAny union · viewItems entry type unknown",
"class: b · JoinedReportBlock (packages/spec/src/ui/report.zod.ts:407) resolves to unknown, because JoinedReportBlockSchema is annotated z.ZodTypeAny. AGENTS.md check:exported-any rationale: "annotate with the real type". Seam: spec:JoinedReportBlock → consumer: none (content/docs/references/ui/report.mdx advertises its shape). Dedupe words: JoinedReportBlock unknown · JoinedReportBlockSchema ZodTypeAny · report blocks type unknown",
"noted, not filed · The viewItem arms type config as unknown (viewItemArmShape takes config: z.ZodTypeAny), so ViewItem, ViewItemWire and ViewMetadata's viewItem arm accept any config at the type level. carrier: none (承接者:无) — in PR #19919 Acceptance notes",
"noted, not filed · No gate catches an exported type alias that resolves to unknown: check:exported-any reads ZodType-of-any annotations. The census script (TypeScript compiler API, about 60 lines) could become one. carrier: none (承接者:无) — in PR #19919 Acceptance notes",
"noted, not filed · AssignmentValue(Parsed) and GetPublishedMetaItemResponse(Parsed) are unknown by design (z.unknown() schemas). Not defects. carrier: none — census only"
],
"deviations": [
"The empty-branch probe push (os-dev rule 1) was a bare git push, before I applied the dispatch's write-pace-only push rule. The two later pushes went through write-pace.",
"The dispatch assumed check:api-surface would report the type change. Refuted: api-surface records export name and kind only, so the gate is green and all three generators wrote zero diff. The PR body states the type change instead.",
"I edited one word in packages/metadata/src/serializers/typescript-serializer-annotation.test.ts's docblock ("as ViewMetadata is" to "once was"), beyond the claim's named files. This PR made that sentence false. It is a comment only; @objectstack/metadata publishes nothing new, so it has no changeset.",
"origin/main moved 2 commits since BASE (beac798, a34c27c), touching neither packages/spec nor packages/metadata. Not merged before opening, a declared narrowing of AGENTS section 10.",
"The PR was opened through the fleet relay (dispatch.mjs pr_create), the AGENTS-mandated write door, rather than a bare curl POST /pulls."
]
}

---

Generated by Claude Code