spec(object-timeline): items describe names objectui as the item-shape owner

[objectstack-fleet]

Fixes #20283

Clause-②: no

What changed

ObjectTimelinePropsSchema.items (packages/spec/src/ui/component.zod.ts) stays z.array(z.unknown()) — no schema-shape change. Its .describe() no longer says "the author owns the item shape". It now names the actual owner: each element is objectui's declared timeline element, @object-ui/types's TimelineFeedItem (variant absent / vertical / horizontal) or TimelineGanttItem (variant: 'gantt'), the arm this node's own variant selects.

content/docs/references/ui/component.mdx was regenerated via gen:schema && gen:docs — never hand-edited.

.changeset/20283-object-timeline-items-element-owner-describe.md — @objectstack/spec patch.

Route taken (per the card, not re-opened)

items keeps z.array(z.unknown()); the value contract stays owned by objectui. Declaring the arms here would fork a second vocabulary. mapping and object-gantt.markers hold the same VALUE posture unchanged.

Verification record

Premise re-measure (required before touching code). At .objectui-sha dd3f7e1be3561d63267d7162f3fc0ac52e72834d (the pin this branch built against), TimelineFeedItem and TimelineGanttItem are declared as plain TypeScript interfaces in objectui's packages/types/src/data-display.ts (lines 2773 and 2834), pinned by objectui's own packages/types/src/__tests__/timeline-item-element-6356.test.ts. data-display.ts imports ChartAxis / ChartType / I18nLabel from @objectstack/spec/ui for the unrelated chart surface, but neither TimelineFeedItem nor TimelineGanttItem imports or re-declares anything from @objectstack/spec — the premise holds, so the route is followed as given (no fork to report).

Four read-point re-reads, objectui ObjectTimeline.tsx at the same pin (git show dd3f7e1be3561d63267d7162f3fc0ac52e72834d:packages/plugin-timeline/src/ObjectTimeline.tsx):

• :254 — const hasInlineItems = Array.isArray(schema.items) && schema.items.length > 0; (loading-state seed)
• :374 — const fetchesForItself = !!schema.objectName && !boundData && !schema.items && !(props as any).data; (fetch-skip gate)
• :546 — if (schema.items) return schema.items; (matches the docblock's citation exactly)
• :771 — const hasAuthoredItems = !!schema.items; (matches the docblock's citation exactly)

All four anchors in the existing docblock (packages/spec/src/ui/component.zod.ts, the object-timeline doc comment) are byte-accurate at this pin — no anchor drift, so no docblock line-number edit was needed. pnpm --filter @objectstack/spec run check:spec-docblock-symbol-anchors also confirms: 4044 anchors resolve, 0 new anchor drift.

The variant describe ("gantt needs authored items") still reads true beside the new items describe — confirmed against ObjectTimeline.tsx:809, if (!hasAuthoredItems && schema.variant === 'gantt') — left unchanged.

Full-repo pin sweep for the stale sentence: grep -rl "author owns the item shape" across the whole tree (excluding node_modules/.git) found exactly the two carriers named at dispatch — packages/spec/src/ui/component.zod.ts and the generated content/docs/references/ui/component.mdx — both fixed here. No test pins the old describe string (grep for it and for becomes a pass-through outside these two files: zero hits), so no fixture triage was needed.

Round 2 correction — a false refusal clause, measured and dropped. The first cut of this describe (and the changeset) also said objectui's strict authoring face "refuses a mismatched arm and undeclared keys" for object-timeline itself. A seat review measured that false at the pin, and this round independently re-measured it before editing: objectui's zod authoring face (AnyComponentSchema / StrictAnyComponentSchema, packages/types/src/zod/index.zod.ts) is a z.discriminatedUnion('type', …) whose member literals — read via git grep -n "z.literal('object-" dd3f7e1be3561d63267d7162f3fc0ac52e72834d -- packages/types/src/zod — are object-grid / object-form / object-view / object-map / object-tree / object-gantt / object-calendar / object-kanban / object-chart / object-gallery / object-data-table and, separately, timeline — never object-timeline. To measure the actual runtime answer rather than infer it, packages/types was exported read-only via git archive dd3f7e1be3561d63267d7162f3fc0ac52e72834d packages/types into a throwaway probe run with tsx against this repo's own built @objectstack/spec (the objectui checkout itself was never built, checked out, or stashed): StrictAnyComponentSchema.safeParse({ type: 'object-timeline', items: [{ label: 'x' }], variant: 'vertical' }) returns a single invalid_union issue, "note": "No matching discriminator", on both the tolerant and the strict face — object-timeline is refused outright as an unrecognized node type, before any per-item judgment runs. A control on a genuine { type: 'timeline', … } node reproduces the arm-selection and unrecognized_keys mechanism exactly (a gantt row's label under variant: 'vertical' draws a named custom issue; a feed item's undeclared date key draws unrecognized_keys) — that mechanism lives on the sibling timeline zod node (TimelineSchema's .superRefine), which object-timeline types against only in TypeScript (ObjectTimeline.tsx's schema: TimelineSchema & { … }), never at runtime for this node. The refusal clause is dropped from the describe and the changeset; nothing else about the route changed. Re-verified after the fix: check:generated (15/15 green), the two component/docs-facing unit test files (component.test.ts, component-element-navigation-17987.test.ts — 366 tests green), check:doc-authoring and check:spec-docblock-symbol-anchors (both green), and a fresh dispatch-gates.mjs reconciliation on the new commit — same 102 derived families as round 1 (the diff only edits words inside the same two describe strings), 99 run green, the same 3 PREREQUISITE NOT MET NOT MEASURED as round 1.

Tests run (this worktree, objectstack-issue-20283, HEAD 0197523247; round 1 ran at HEAD 3635807a7f)

• pnpm --filter @objectstack/spec build — exit 0 (rebuilt after merging origin/main).
• pnpm --filter @objectstack/spec check:generated — exit 0, all 15 generated artifacts up to date (pre- and post-merge).
• pnpm --filter @objectstack/spec test — 573 test files passed (573), 16809 tests passed | 1 todo.
• pnpm --filter @objectstack/spec typecheck (tsc --noEmit + check:scripts-typecheck + check:test-typecheck) — exit 0.
• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran (an annotated ran-list file) reconciliation: 102 derived families, 99 run green, 3 NOT MEASURED (PREREQUISITE NOT MET, exit 3), 0 unrun — pnpm --filter @objectstack/spec run check:skill-examples, pnpm check:dual-build-cjs-loads, pnpm check:lean-entry-closure each refused locally before measuring anything because they read BUILT output of unrelated packages (@objectstack/client-react, and — for dual-build-cjs-loads — the whole workspace's dist/, 82+ packages) that this describe-only change does not touch and that a full local build did not fit this task's floor-tier scope; the shared os-verify-lock queue was also heavily contended by sibling agents' builds throughout this run. CI's full farm covers these.
• pnpm check:doc-authoring — exit 0: 16748 customer-facing strings across 1170 spec sources clean, no internal issue-id references (the new describe carries none).
• pnpm check:nul-bytes, pnpm check:merge-driver, pnpm check:objectui-pin-citations, check:changeset-gate-self-tests (check:empty-changeset / check:adr-0087-registration / check:changeset-no-major) — all exit 0.
• Dependency-closure build (①): none — packages/spec has no workspace dependencies, so the closure is empty by construction.
• Downstream consumer closure: not run — this is a .describe() text change only; the compiled .d.ts type surface is byte-identical (confirmed by check:api-surface and check:export-origins both green with zero diff), so no downstream package's typecheck is implicated.

Acceptance notes

No out-of-scope findings of class (a)/(b)/(c) surfaced while working this card. origin/main advanced twice during this round (to fb194c70e5, then merged again to fb386074f5 after a clean git merge origin/main with no conflicts and no overlap with the two touched files); rebuilt and re-ran check:generated after the merge, still all 15 green.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 137 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 03b19d9cfdb7f0811dc27398b51b44d332a2ed88 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 97e416b8cb82c2649b3a47b61eb9fcef09072d47 — the merge of head 891830acdf29765700ac43c36a38aad9348543fd into base 03b19d9cfdb7f0811dc27398b51b44d332a2ed88, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 97e416b8cb82c2649b3a47b61eb9fcef09072d47 && git checkout 97e416b8cb82c2649b3a47b61eb9fcef09072d47
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 03b19d9cfdb7f0811dc27398b51b44d332a2ed88 891830acdf29765700ac43c36a38aad9348543fd && git checkout -B drift-repro 03b19d9cfdb7f0811dc27398b51b44d332a2ed88 && git merge --no-ff 891830acdf29765700ac43c36a38aad9348543fd

node scripts/docs-audit/affected-docs.mjs --json 03b19d9cfdb7f0811dc27398b51b44d332a2ed88

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 891830acdf29765700ac43c36a38aad9348543fd
Local-runs: none

Inputs, and nothing else: card #20283 (body; triage grade 5859517446, unlock 5879567964, claim 5880073803, os-dev-reports 5881158750 / 5881621744 / 5881658978); PR #20531 (body, its one comment 5881140085, file list, and the net diff against origin/main 03b19d9cfdb7, which is also the base the head's CI merge used); the 32 check-runs on the head, read once; and the objectui pin .objectui-sha dd3f7e1be3561d63267d7162f3fc0ac52e72834d, read as git objects. Nothing built, run or re-run; no worktree.

① Derived judgments

Net diff: three files, +9 / -2 — one .describe() string, its generated mirror, one changeset. Head repo is the base repo (not a fork). No governed-surface path in the file list. The file surface equals the claim's exactly; no objectui edit; the four branch commits net to exactly the PR's file list.

1. Accept set of items — UNCHANGED, right. items: z.array(z.unknown()).optional() is byte-identical before and after (packages/spec/src/ui/component.zod.ts:5209); only the describe string moved. That is the claim's route and the file's VALUE posture (:3285-3290: the keys are the spec's, the value contract still lives in objectui; mapping at :5223 holds the same way). No key, enum member, union arm, export or registration is added anywhere in the diff.
2. Public surface — UNCHANGED, right. No export added, removed or renamed; api-surface/ untouched; a describe-only edit cannot move the compiled .d.ts.
3. Every clause of the new describe, read against the pin, not the dev's prose:
   • "objectui's declared timeline element" — TRUE. packages/types/src/data-display.ts:2894 ("The element is declared: two arms, and variant picks one"); items is an array of TimelineFeedItem or TimelineGanttItem at :2932.
   • "@object-ui/types's TimelineFeedItem … or TimelineGanttItem" — TRUE. Package name @object-ui/types (packages/types/package.json); both interfaces declared at data-display.ts:2773 and :2834, exported from packages/types/src/index.ts:261-262.
   • feed arm = node variant absent / vertical / horizontal; gantt arm = variant: 'gantt' — TRUE. data-display.ts:2899-2902; the zod mirror's TIMELINE_ITEM_ARMS (packages/types/src/zod/data-display.zod.ts:1201-1216) and its refinement's "absent ⇒ vertical" (:1219-1220); objectui's own pin timeline-item-element-6356.test.ts:161 ("absent reads as vertical").
   • "the arm this node's variant selects", for an object-timeline node — TRUE. ObjectTimelineProps.schema is TimelineSchema intersected with the object-bound keys (packages/plugin-timeline/src/ObjectTimeline.tsx:165-219), and the intersection redeclares neither items nor variant, so the node's element type and its three-value variant are TimelineSchema's own. Authored items pass through untouched (:546, :771) into effectiveSchema.items (:874) and on to TimelineRenderer (:942), whose branch is chosen by variant (renderer.tsx:1419 horizontal, :1455 gantt, vertical otherwise) and reads only that arm's keys. ObjectTimelinePropsSchema.variant here is the same three values (:5211).
   • "the renderer becomes a pass-through" — TRUE: :546 if (schema.items) return schema.items;. The retired sentence "the author owns the item shape" is gone from every carrier at the head (git grep over the whole tree: only the changeset quotes it, as the text being retired).
   • The round-1 refusal clause ("refuses a mismatched arm and undeclared keys") — GONE from the describe, from component.mdx, from the changeset and from the PR body's "What changed" paragraph; it survives only in the body's verification record as history, which is the right place. The removal is right, confirmed statically: git grep object-timeline over packages/types/src/zod at the pin returns nothing; the component union's object-* literals are grid / form / view / map / tree / gantt / calendar / kanban / chart / gallery / data-table, plus the sibling timeline. No runtime face judges an object-timeline node's items, so a refusal clause would have advertised enforcement that does not exist (Prime Directive chore: version packages #10). Round 1's clause was false; the dev measured it and removed it.
   • Non-blocking observation: TimelineFeedItem carries its own variant key, a marker colour (TimelineItemVariant = default / success / warning / danger / info, data-display.ts:2751, :2785). The parenthetical after TimelineFeedItem names the NODE's variant values, and the sentence's closing clause ("the arm this node's variant selects") is what fixes that reading; TimelineGanttItem has no variant key at all, so the gantt parenthetical admits no other reading. Not a false clause. A later edit that drops the closing clause would make it one.
4. No second vocabulary — right. The describe names two types by name and the node's own three variant values (already this schema's enum one line down); no key list (time, title, label, …) is copied. Consistent with triage 5859517446 and the claim's ⛔.
5. component.mdx is the generator's output — right. Row template | **key** | type | required | desc | (packages/spec/scripts/lib/schema-section.ts:544); desc is escapeMdxDescription(description + externalVocabularyNote + dimensionlessNote) then backslash and pipe escaping (:536-543). The new describe carries no brace, no angle bracket, no pipe, no backslash and no newline, and items declares neither externalVocabulary nor dimensionless (both notes read schema metadata, never prose), so the cell is the describe byte-for-byte — compared at the head: 383 bytes each, identical. The type cell any[] and the optional cell are unchanged because the shape is. Exactly one generated carrier exists (json-schema/ is gitignored). CI's own answer, check:docs in Type Check · source gates: success on this head.
6. Docblock anchors — right. The object-timeline docblock's items read points (:254, :374, :546, :771) are byte-accurate at the pin; :809 (if (!hasAuthoredItems && schema.variant === 'gantt')) still holds, so the neighbouring variant describe ("gantt needs authored items") stays true beside the new one. No anchor edit was needed and none was made.
7. Premise (no fork) — holds. data-display.ts at the pin imports only ChartAxis / ChartType / I18nLabel from @objectstack/spec/ui (:18); both timeline interfaces are declared locally, and nothing in this repo imports them.

Gate coverage — the 32 check-runs on the head, read once at judgment:

• Concluded success (13): Type Check · source gates (carries check:docs, the mdx parity above; check:authorable-surface; check:generated --reconcile-only; check:export-origins; check:objectui-pin-citations), Check Changeset, Governed Surface Queue Guard, Spec property liveness, Check Documentation Links, Flag docs affected by code changes (its comment 5881140085: nothing to list, computed on the merge of this head into 03b19d9cfdb7), Check PR Size, Auto Label, filter, and the four PR/card consistency checks (The card this PR closes must claim this branch, No other open PR may claim the same issue, No other open PR may claim the same single-writer path, Part-of PR must not also close its card).
• Not concluded at the read (in_progress, 17) — named, not presumed green: Lint & Repo Gates (carries pnpm lint, check:doc-authoring, check:spec-docblock-symbol-anchors, check:changeset-gate-self-tests), Type Check · workspace, Type Check · consumer gates (check:api-surface, check:exported-any, check:skill-examples), Type Check · debt ledger, Test Core (1/6) through (6/6) (the spec unit tests ride the affected shard), Build Core (check:dual-build-cjs-loads, check:lean-entry-closure), Build Docs (the MDX compile), Dogfood Regression Gate (1/3) through (3/3), Dogfood Verify CLI, Temporal Conformance (live PG + MySQL).
• Skipped by design (2): Console Pin Gate (the filter job's console output is false — the diff touches neither the pin nor the console), Packed-tarball smoke (opt-in).
• Of the required seven contexts: one concluded success (Governed Surface Queue Guard); three in progress (Lint & Repo Gates, Build Core, Temporal Conformance (live PG + MySQL)); three aggregates had no check-run on the head yet at the read (TypeScript Type Check, Test Core, Dogfood Regression Gate) — their lanes and shards are the in-progress runs named above.
• Failures: none at the read, so nothing to attribute to this diff. Every derived family I could map to a workflow step has a check-run on this head; none is CI-less. One judgment has no CI family at all and is answered only here: the truth of the describe against the objectui pin — a prose claim about a sibling repo's types, which check:spec-docblock-symbol-anchors (line anchors) does not read.

② Semver level

@objectstack/spec: patch — right. A .describe() string is runtime metadata that ships in the built package and in the generated JSON Schema and reference docs, so the diff publishes; skip-changeset would be wrong. Nothing widens or narrows, so minor and BREAKING are wrong. Clause-②: no (PR body; claim 5880073803) — right: none of the four widening tells (new key, new closed-set member, new export row, new registration) appears in the added lines, and the accept set of items is the same universal z.unknown() before and after. The changeset says only what ships: paragraph one the correction, paragraph two why it is documentation-only and not value-tightening; the round-2 "Correction" paragraph is gone (round-3 commit 891830acdf), so no unshipped history reaches CHANGELOG.md. Check Changeset: success on this head.

③ Boundary flags

• open_questions: [] in rounds 1, 2 and 3 — nothing to answer, nothing to escalate.
• out_of_scope_findings: [] in all three rounds.
• Round-2 deviations, each answered:
  1. Measuring the refusal claim by a git archive export of objectui's packages/types at the pin plus a tsx probe against this repo's built spec — a READ of objectui (no checkout, edit or stash), inside the claim's ⛔ (no objectui edit). Its finding (no object-timeline arm) is confirmed here statically — ACCEPTED.
  2. Container restart mid-round-2, resumed from the surviving worktree diff and re-verified — the head's own check-runs re-derive every family; ACCEPTED.
  3. Worktree recreated for round 2 with the prerequisite builds re-run — process cost only; ACCEPTED.
• The dev's three NOT MEASURED families (check:skill-examples, check:dual-build-cjs-loads, check:lean-entry-closure): each has a CI carrier on this head (Type Check · consumer gates; Build Core for the other two), all pending at the read — not escalated; the owning seat reads their conclusions before enqueue.
• The claim's "stop on breach": no breach reported, none found.
• Nothing escalated.

Implemented-by: claude/issue-20283-timeline-items-element-owner
Reviewed-by: session_014EJ1ED8X4MMrT18BhVx4tx

VERDICT: PASS

---

Generated by Claude Code