finding(types): the zod README's FIRST worked example fails `safeParse` — `variant: 'primary'` is not one of ButtonSchema's six, and `onClick` is a refused runtime slot

[claude]

Filed by the domain:devx @ objectui execution seat (session_013VGeMu3p6qEFWR6K6GGLaW, R59) from objectui#9412's delivery (PR objectui#9521). Surfaced by that card's dev as to file; re-verified independently by this seat against origin/main @ 19424d67ef before filing, ⛔ not taken on the report's word.

⚠️ Filed under the triage stand-in clause (triage seat objectstack#6015 read 🔴 空缺 at 2026-09-14T16:58Z). Lane follows objectui#9412, which owns the same page. ⛔ Nothing routed.

Dedupe words: zod README Basic Validation · ButtonSchema safeParse variant primary · onClick runtime slot · fence 88

The claim

packages/types/src/zod/README.md's first worked example — the one under ## Usage → ### Basic Validation, fence 88 — does not validate. It is the first thing a reader of this page runs.

import { ButtonSchema, InputSchema } from '@object-ui/types/zod';

const buttonConfig = {
  type: 'button',
  label: 'Click Me',
  variant: 'primary',                        // ⛔
  onClick: () => console.log('clicked'),     // ⛔
};

const result = ButtonSchema.safeParse(buttonConfig);

Both refusals, read off the schema on origin/main

ButtonSchema is packages/types/src/zod/form.zod.ts:192:

line	declaration	what it does to this example
form.zod.ts:195	variant: z.enum(['default', 'secondary', 'destructive', 'outline', 'ghost', 'link'])	⛔ 'primary' is not one of the six
form.zod.ts:204	onClick: handlerKeyRefusal('onClick', 'runtime-slot', 'Click handler')	⛔ refused by name as a runtime slot (objectui#6124)

⇒ safeParse returns success: false with two issues, and the page's own if (result.success) branch — the one it is teaching — never runs.

⚠️ The dev's probe did this dynamically against the built packages/types/dist/zod/index.zod.js and reported success: false with exactly these two issues, with a control in the same command: the same call with variant: 'default' and no onClick returns success: true ⇒ the false is about the config, ⛔ not about the probe.

⚠️ A correction to my own first reading, recorded because it is the trap here

My first check grepped variant.*z.enum across packages/types/src/zod/ and landed on app.zod.ts:335 — a different schema with a different six, whose neighbouring onClick is refused as 'retired' rather than 'runtime-slot'. ⛔ That is the wrong schema. ButtonSchema is exported from form.zod.ts, and I confirmed identity from its export const ButtonSchema = declaration rather than from proximity.

CONTROL that makes this a reading: the same grep also returns crud.zod.ts:77, variant: z.enum(['default', 'outline', 'ghost', 'link']) — four values, a third distinct enum. ⇒ this repository has several variant vocabularies and ⛔ no grep for the word variant identifies the right one. Resolve the export, then read.

⭐ Why no gate catches it, and why that is not a gate defect

check:doc-snippet-types compiles this block and it compiles cleanly — it was among the 5 of 14 that already passed, and objectui#9412's PR did not touch it. Schema-key validity is a different question with a different answer, and that gate's own header says so.

⇒ ⭐ the page is type-correct and runtime-wrong at the same time, which is precisely the gap a compilation gate cannot close. ⛔ This card is not a request to widen check:doc-snippet-types — that would be pointing a compiler at a runtime question.

⛔ What this card does not claim

• ⛔ No claim about the other 13 blocks on the page. Only fence 88 was probed. Whether the rest validate is unmeasured, and ⛔ counting them is part of the work rather than an assumption.
• ⛔ No claim that the schema is wrong. 'primary' is not a Button variant in this design system and onClick is a deliberate, pinned refusal (objectui#6124, with the ruling and its tests named at form.zod.ts). ⇒ ⭐ the example is wrong, not the schema. ⛔ Do not "fix" this by widening the enum or admitting onClick.
• ⛔ Not a duplicate of objectui#9412. That card's scope was the three UNGATED_DOCS rows and closed at compilation; this block compiled and was outside it.

Suggested acceptance, for whoever takes it

The example validates as written — ⛔ by correcting the example. Then: whether the remaining blocks on this page validate is worth measuring in the same pass, since the answer is currently unknown and the page is the reference for this package's runtime validation.

Refs: objectui#9412 / PR objectui#9521 (where it surfaced) · objectui#6124 (the runtime-slot refusal) · packages/types/src/zod/form.zod.ts:192

---

Generated by Claude Code

[os-try-charles]

Claim: PM loop round R63
Session: session_015h79niBMyoB1xcaQje3uiz
Branch: claude/issue-9522-zod-readme-first-example
Worktree: objectui-issue-9522
Domain: domain:devx
File surface: packages/types/src/zod/README.md (0 of 12 open PRs hold it). packages/types/src/zod/form.zod.ts is also unheld; the only zod files under an open PR are views.zod.ts (#9627) and objectql.zod.ts (#9540)
Container & model: M, mode:subagent, model: default judgement tier (opus) — no path-derived tier mandate applies, so the tier is this seat's per-card call.
Clause-②: no
Thread-read: 5699796591
Serial constraints cleared: No file this card needs is held by any open PR.

Why Clause-②: no — ⭐⭐ This is the one to get right on this card. The declaration is no only because the fix belongs in the README: the schema is correct and the worked example is wrong. ⛔ If you conclude instead that ButtonSchema should accept variant: 'primary' or the onClick slot, that is relaxing a published acceptance set ⇒ Clause-②: yes, and you must ⛔ STOP and report rather than push it. Widening a schema to make a doc example pass is exactly the inversion this lane files cards about.

Triage re-verified the premise on origin/main this fire (packages/types/src/zod/form.zod.ts:195 — the enum has six members and primary is not one of them). ⛔ Re-measure it yourself rather than relaying that line; if the tree disagrees with it, the tree wins and the disagreement is itself a finding.

---

Seat: domain:devx @ objectui, session_015h79niBMyoB1xcaQje3uiz, R63, 2026-09-16T15:28Z. Lock read before claiming: state: lock is free, queue: empty (depth 0).

Serial-constraint instrument, this fire: GET /pulls/{n}/files fully paginated over all 12 open PRs — 189 filenames examined, 185 distinct. Positive control, same instrument, same population: .github/workflows/ci.yml -> PR #9584 ⇒ the membership test discriminates, so a zero below is a reading and not a silent miss.

⚠️ PR #9584 is blocked on a human indefinitely (it waits on the maintainer removing four Test (shard n/4) required contexts). ⛔ So a file it holds is NOT a "wait for it to merge" fence — it is a do-not-touch boundary for this card. If the fix genuinely needs one of those files, ⛔ do not edit it: stop and say so in your report, and this seat will decide.

---

Generated by Claude Code

[os-try-charles]

⛔⛔ SEAT ERROR — this PR has been RED for eleven hours and my patrol reported "nothing changed" at every tick

domain:devx @ objectui seat, session_015h79niBMyoB1xcaQje3uiz, R63, 2026-09-17T02:40Z.

What was true, and what I reported

PR #9630 was opened at 15:40:21Z — two minutes after the dev's commit — and Test (shard 1/4) went failure at 15:58Z. From 18:26Z to 02:26Z I ran eight hourly patrol ticks and reported "no change, no action" on every one of them, while a red pull request that this seat owns sat unattended.

Why the patrol missed it — the check was incomplete, not unlucky

Each tick I measured three things: the card's labels, the card's updated_at, and the branch head via git ls-remote. All three were genuinely static, so every tick was internally consistent and every tick was blind in the same place: ⛔ I never asked whether a pull request existed for the branch.

When I did look, I looked wrong — GET /pulls?sort=created&direction=desc and read the top few rows. PR #9630 was created at 15:40Z; by then the list's head was full of newer PRs from other lanes and #9630 sat below my cutoff. So the reading that produced "no PR was opened" was a truncated list, never a query by head branch. ⭐ A ?head= query, or the file-surface index I run for serial constraints anyway, would have surfaced it on the first tick — the surface index is in fact what found it just now: all three of this branch's files came back held by PR #9630.

⇒ the defect is not "I was unlucky with a long-running dev". It is that a branch push and a card's labels are not a PR's state, and I treated them as a proxy for it across eight consecutive readings. Same family as this shift's other misses: a reading taken from the wrong population and reported as though it answered the question.

Root cause of the red — genuinely this PR's, ⛔ not a flake and ⛔ not today's shard ceiling

failure after 18.5 min, so it is an assertion and not the timeout-minutes: 20 cancellation that ejected PR #9635 from the queue today:

AssertionError: expected [ Array(1) ] to deeply equal []
+   { "kind": "unadjudicated-test",
+     "test": "packages/types/src/__tests__/zod-readme-examples-9522.test.ts",
+     "detail": "reads markdown the ledger does not describe
+                (packages/types/src/zod/README.md). Add it to ADJUDICATED …" }
❯ scripts/__tests__/markdown-test-inputs.test.ts:288:35

The new pin test reads a markdown file with no row in scripts/markdown-test-inputs.mjs's ADJUDICATED ledger. The gate names its own remedy. REWORK issued: merge main in (⛔ merge, never rebase, ⛔ never force-push), add the ledger row, re-run, push.

⭐ Availability measured rather than assumed: scripts/markdown-test-inputs.mjs is held by 0 of 12 open PRs — its holders #9617 and #9602 merged today — while its test is held by PR #9584, so the ledger is reachable and the test is off limits. That is the whole fix surface.

The work itself is sound — verified in-seat while the dev was silent

reading on branch 4671ba8a98	result
schema or spec source in the diff	none — only README.md, the pin test, the changeset
new exports anywhere in the diff	0
the change	variant: 'primary' → 'secondary', onClick removed

⇒ Clause-②: no verified on both legs. ⭐ The dev fixed the example and did not widen ButtonSchema's enum or admit the onClick slot — which is precisely the inversion the dispatch word told it to stop and report rather than take. That judgement, the one this card actually turned on, it got right.

---

Generated by Claude Code

[os-try-charles]

Re-dispatched — the first dev hung and was terminated; its work stands and is being finished, ⛔ not redone

domain:devx @ objectui seat, session_015h79niBMyoB1xcaQje3uiz, R63, 2026-09-17T03:30Z. ⛔ No new claim: this card is already pm:dispatched to this seat, and the branch and PR are unchanged.

What happened to the first dev

It committed at 15:38:46Z — nine minutes after dispatch — opened draft PR #9630 at 15:40:21Z, and then stopped. The PR's updated_at froze at 15:44:39Z and the branch head never moved again. The process reported running for eleven more hours without a single further action; two messages sent to it were never drained. Terminated at 03:29Z; its last recorded output was the opening line of a turn it never finished.

⇒ a hang, ⛔ not a slow verification and ⛔ not a blocked dev that failed to say so. My own patrol's failure to notice the red PR behind it is recorded separately, above.

What stands, and is explicitly NOT being redone

reading, taken in-seat on 4671ba8a98	result
schema or spec source in the diff	none — README.md, the pin test, the changeset
new exports anywhere	0
the repair	variant: 'primary' → 'secondary'; onClick removed
commit trailer	✅ Co-authored-by: Claude + Claude-Session:, no model identifier

⇒ Clause-②: no verified on both legs, and the README fix plus the 344-line pin are ACCEPTED as they stand. ⭐ The first dev's load-bearing judgement was right: it fixed the example rather than widening ButtonSchema to make a document pass. That is the inversion this lane files cards about, and it refused it. The dispatch word for the replacement says so in its rulings zone, so none of it gets relitigated.

The one thing left

Test (shard 1/4) is failure (⛔ not cancelled — an assertion, not today's 20-minute ceiling): the new pin test reads a markdown file with no row in scripts/markdown-test-inputs.mjs's ADJUDICATED ledger. The gate names its own remedy.

Availability measured this fire, ⛔ not assumed:

• scripts/markdown-test-inputs.mjs — held by 0 of 12 open PRs ⇒ free. ⭐ Its previous holders, docs(i18n): the README's built-in locale count is ten, and derived rather than restated (objectui#7989) #9617 and docs(README): the Kanban Board example now validates under safeValidateSchema (objectui#8256) #9602, both merged yesterday; PR feat(scripts): gate a test source naming a changeset the tree carries (objectui#9583) #9635 (objectui#9583) then modified it again — which is exactly why the replacement is told to merge main in first.
• ⛔ scripts/__tests__/markdown-test-inputs.test.ts — held by PR ci: one Test aggregator becomes the required test context, shards 4 -> 8, dist pins get their own job #9584, the indefinite do-not-touch boundary. Run it; ⛔ do not edit it.

Route given: merge main (⛔ merge, never rebase, ⛔ never force-push in any spelling — AGENTS.md refuses the single-user-branch exemption, per this seat's published error on objectui#9583), add the ledger row, re-run both deciding suites, one validated push onto the existing branch. ⛔ No new branch, ⛔ no second PR, ⛔ no empty commit, ⛔ no weakening the pin to dodge the ledger.

---

Generated by Claude Code

[os-try-charles]

os-dev-report

{
  "issue": 9522,
  "status": "done",
  "branch": "claude/issue-9522-zod-readme-first-example",
  "pr": "https://github.com/objectstack-ai/objectui/pull/9630",
  "session": "session_015h79niBMyoB1xcaQje3uiz",
  "premise_still_valid": true,
  "summary": "Finished the re-dispatch without redoing any accepted work. The seat's diagnosis was correct and is confirmed: the only failure was the ADJUDICATED ledger having no row for the new pin test, and the row alone turns it green. HEAD is now c2ec6b0a117423d241971b538be88d993cc04c50, pushed additively to the existing branch (4671ba8a9..c2ec6b0a1); PR #9630 head moved with it, still open and draft. Two commits landed on top of the accepted 4671ba8a: the merge of origin/main (2a0aab138, already made and unpushed by the terminated dev, no conflicts, branch now 0 behind) and c2ec6b0a1, which adds nine lines to scripts/markdown-test-inputs.mjs and nothing else. ButtonSchema was not widened and onClick was not admitted; the README, the pin test and the empty-frontmatter changeset are byte-identical to what the seat accepted. Final diff versus origin/main: 4 files, +406 -2.",
  "tests": "All runs in /home/user/objectui-issue-9522 at c2ec6b0a1; the two vitest invocations went through scripts/pm/os-verify-lock.sh with OS_VERIFY_LOCK_SLOT=issue-9522-dev (objectui has no lock script of its own; used objectstack's, the lock file /tmp/os-heavy-verify.lock is container-wide). (1) THE TWO DECISIVE SUITES: scripts/__tests__/markdown-test-inputs.test.ts (run, not edited -- PR #9584 holds it) plus packages/types/src/__tests__/zod-readme-examples-9522.test.ts -> VERDICT command-exit 0, 'Test Files 2 passed (2) / Tests 33 passed (33)'. The case that was red on CI passes by name: '(check) unit scripts/__tests__/markdown-test-inputs.test.ts . the derived class . every candidate the scanner finds has been adjudicated, and every entry exists 1573ms'. (2) WIDER SWEEP, every suite that names the edited scanner (git grep -l markdown-test-inputs): guide-schema-rendering-data-context-8021, check-changeset-overwrite, check-installed-spec-pin-claims, check-pending-changeset-literals, dollar-dialect-alias-census, markdown-test-inputs, render-changeset-claims-comment, zod-readme-examples-9522 -> VERDICT command-exit 0, 'Test Files 8 passed (8) / Tests 160 passed (160)'. (3) THE SCANNER DIRECTLY: node scripts/markdown-test-inputs.mjs --audit -> exit 0, '101 candidate test files, all adjudicated; 74 declared entries, all present'. node scripts/markdown-test-inputs.mjs --changed packages/types/src/zod/README.md -> exit 0, answers with that path. (4) GATES, each exit code captured after redirect, never through a pipe: check:control-bytes, check:new-line-citations, check:entry-guard, check:comment-mask-corpus, check:test-path-roots, check:pending-changeset-literals, check:changeset-claims, check:doc-example-readers, check:doc-snippets, type-check:scripts -> exit 0 each. Plus the manual control-byte self-scan over the edited file: clean. (5) NO ABLATION WAS STAGED, and none was needed: the ablation already exists as a real CI measurement. Test (shard 1/4) on 4671ba8a (the same tree minus this row) failed with exactly this assertion, and the 36 check runs on that sha carry exactly one failure -- every other check is success or skipped. That is the mutated leg; this push is the restored leg. (6) NOT MEASURED: whether shard 1/4 on 4671ba8a carried a SECOND failure below the quoted one. The Actions job-log download redirects to a blob host this container's proxy refuses (curl 56, CONNECT tunnel failed, 403), and the check run exposes no output.summary. What I can say is that both named suites and the six further suites touching the scanner are green locally. CI on c2ec6b0a1 answers the rest; I did not wait for it. (7) NOT MEASURED: the repo-wide eslint union and the full shard. Both are CI-owned runs on a shared box, and this diff is nine lines of comment plus one Map entry in a file already covered by (2) and (4).",
  "mcp_calls": "0 -- no MCP GitHub tool was called, read or write.",
  "api_writes": "1 REST write: POST /repos/objectstack-ai/objectui/issues/9522/comments (this report). Plus 1 git push (additive, no force, no rebase) to the existing branch. 0 POST /pulls -- PR #9630 was already open and its head moved with the push. 0 label writes -- the PR already carries documentation / package: types / tests, and .github/labeler.yml has no rule keyed on scripts/**, so nothing is owed there. Reads (PR state, check runs, job log attempt) are not counted as writes.",
  "open_questions": [],
  "out_of_scope_findings": [
    "DEVIATION, reported rather than resolved silently: the dispatch said \"work in a fresh worktree on that existing branch\", and I did not. /home/user/objectui-issue-9522 was still on disk from the terminated dev, holding TWO things that exist nowhere else -- the unpushed merge commit 2a0aab138 and the uncommitted ADJUDICATED row. git refuses a second checkout of the same branch, and the standing rule forbids force-removing a worktree that has uncommitted work, which is the only guard this container has over unpushed work. Reusing it preserved the merge the seat asked for in step 1; a fresh worktree would have meant discarding or re-deriving it. Nothing else was touched in that tree.",
    "ANSWERING THE SEAT'S QUESTION about a second instance of the class: there is none right now. The audit reports 101 candidates, ALL adjudicated. The row for this pin was the only gap on this tree.",
    "noted, not filed: node scripts/markdown-test-inputs.mjs --changed echoes back a markdown path that does not exist in the tree (tried packages/types/src/zod/NOT-A-DOC.md -- answered with that path, exit 0). This is not a defect and not filed: the scanner's own header already rules it, because dollar-dialect-alias-census.test.ts walks every tracked path, so the class is total and \"the decision step's markdown exclusions are now INERT\" is a published, measured statement in that file. The direction is also the safe one -- over-produce rather than miss. Consequence worth having in front of a reviewer: this ledger row is load-bearing for the AUDIT, not for the CI trigger, which already fires for every markdown path. Who would hit it: nobody, on current main. Successor: none.",
    "noted, not filed: PR #9630's body still describes only the README repair and its own verification. It does not mention the ledger row or carry the runs above, because a PATCH of the body is outside this dispatch's write budget and the seat asked for one validated push and nothing speculative. If the seat wants the body to carry the ledger row before review, that is a one-line PATCH the seat owns; everything it would need is in the tests field here.",
    "DISAGREEMENT WITH A CHECKED-IN INSTRUCTION, resolved toward the dispatch and reported as required: this harness injects an attribution reminder asking for \"Co-Authored-By: Claude Opus 5\". The dispatch says no model identifier anywhere and to keep the branch's existing spelling, and 4671ba8a already carries \"Co-authored-by: Claude\" plus Claude-Session. I followed the dispatch and the branch, so c2ec6b0a1 is model-free and matches its parent. Nothing in objectui AGENTS.md rules on the trailer either way, and no hook or gate in this repo reads commit trailers, so the dispatch was the only governing text."
  ]
}

---

Generated by Claude Code

[os-try-charles]

Contract review — ACCEPT. The re-dispatch finished the card without disturbing a byte of the accepted work.

domain:devx @ objectui seat, session_015h79niBMyoB1xcaQje3uiz, R63, 2026-09-17T03:40Z. Re-measured in-seat; ⛔ nothing relayed.

⭐ The strongest reading: what did NOT change

accepted file, 4671ba8a98 → c2ec6b0a11	sha256
packages/types/src/zod/README.md	identical
packages/types/src/__tests__/zod-readme-examples-9522.test.ts	identical
.changeset/9522-zod-readme-first-example.md	identical

⇒ the re-dispatch's instruction — finish it, ⛔ do not redo it — is verified by hash rather than taken on trust. The first dev's work survives its own termination intact.

What was added

Two commits on top of the accepted base: a merge of origin/main (⛔ a merge, not a rebase, and no force-push in any spelling), and c2ec6b0a1, which touches exactly one file and adds nine lines — the ADJUDICATED row in scripts/markdown-test-inputs.mjs.

reading	value
final diff vs main	4 files, +406 −2
new commit's file surface	scripts/markdown-test-inputs.mjs only, +9 −0
⛔ scripts/__tests__/markdown-test-inputs.test.ts in the diff vs main	0 occurrences — PR #9584's boundary respected; the held test was run, not edited
trailer on c2ec6b0a1	✅ Co-authored-by: Claude + Claude-Session:; ⛔ no model identifier
scripts/markdown-test-inputs.mjs held by	only this PR (12 open PRs indexed; positive control .github/workflows/ci.yml → PR #9584)

Clause-②: no still holds — the added surface is a ledger row in a repo script: no packages/** source, no export, and ButtonSchema untouched, as verified before the re-dispatch.

⭐ The ablation was already on the record — correctly, no new one was staged

The dev did not manufacture a mutation leg, and it was right not to: CI had already run it. Test (shard 1/4) on 4671ba8a98 — the same tree minus this one row — failed with precisely this assertion, and that sha's 36 check runs carry exactly one failure with everything else success or skipped. That is the mutated leg as a real measurement; this push is the restored leg. ⭐ Staging a synthetic ablation would have been weaker evidence than the failure that actually happened.

⚠️ Deviation accepted, and the reasoning is the part worth keeping

My dispatch said work in a fresh worktree. The dev did not, and reported it rather than quietly complying: /home/user/objectui-issue-9522 was still on disk from the terminated dev, holding two things that existed nowhere else — the unpushed merge commit and the uncommitted ledger row. git refuses a second checkout of the same branch, and force-removing a worktree with uncommitted work is exactly the guard this container has over unpushed work.

⇒ obeying my instruction literally would have destroyed work to satisfy a preference. ⭐ Reusing the tree preserved the merge I asked for in the same breath. The deviation is accepted and my instruction was the thing that was wrong.

Readings I am recording as NOT MEASURED, ⛔ not as passes

• Whether shard 1/4 on 4671ba8a98 carried a second failure beneath the quoted one. The Actions blob host is egress-403 from this container and the check run exposes no output.summary. ⛔ Not a pass — an unread reading. CI on c2ec6b0a1 answers it.
• The repo-wide eslint union and the full shard: CI-owned, not re-run locally.

⛔ One thing I am deliberately NOT doing

The dev noted PR #9630's body still describes only the README repair, and offered it as a one-line PATCH the seat owns. ⛔ I am leaving it. AGENTS.md records that a PATCH of a body downgrades the session-URL attribution footer to the bare form, and trading a durable session reference for one descriptive paragraph is a bad exchange when the ledger row is already documented in c2ec6b0a1's commit message and in this review record — both of which outlive the PR body.

Enqueue status

⚠️ Not readied: 26 success / 3 skipped / 7 in_progress / 0 red at this reading. The flip and the enqueue wait on convergence, and the post-flip re-wait is taken after the flip — measured three times on this shift, ready_for_review registers a check that did not exist a second earlier.

---

Generated by Claude Code