finding(docs): AGENTS.md documents a `BaseSchema.events` key that no schema declares and no renderer reads — `BaseSchemaCore` is passthrough, so a node authored from the instruction file is silently discarded

[os-sam]

Filed by the domain:spec @ objectui os-dev seat while executing objectui#6910 (PR #9552). Out of that card's scope, so filed rather than fixed. ⛔ No labels set by this seat.

⚠️ Correction, same seat. The census table first published on this card was taken with a broken instrument — it matched only the JSON-quoted "events": spelling, which structurally cannot see a TypeScript object literal — and it reported that the only authored events keys were TimelineSchema.events. That was wrong in both directions. The table below is re-measured with the corrected instrument and carries its corpus, ref and controls. The same flawed clause had reached PR #9552's NOTE and was caught in contract review; it is repaired there. The defect is named rather than quietly overwritten, because it is the same one this card is about.

The trap

AGENTS.md is the first file an AI agent reads in this repository. Its section 4, "The JSON Protocol (the DNA)", presents the node shape and includes an optional events member typed as a record of event-name string to ActionSchema array, commented onClick -> [Action1, Action2]. Commandment #4, "Action system", then shows an authored document declaring behaviour under an "events" key.

No schema in this repository declares that key, and nothing reads it. An author — especially an AI author, which is who that file is written for — writes it, and the value is kept by the parser, judged by nothing, and run by nothing. A silent discard, with no signal in either direction.

Measured at 53df540f08, corpus 5,484 tracked files under packages/ apps/ examples/

Controls in the same pass, same command shape: className: → 519 occurrences (fires); absent token qqzz_absent_token_9999 → 0.

reading	result
events member on the TypeScript BaseSchema interface	absent
events member on BaseSchemaCore (the zod mirror, 21 members)	absent
schema.events read sites	0
props.events read sites	0
events: { — the node-level record, i.e. the AGENTS.md sketch shape	10 occurrences in 8 files
events: [ — unrelated hook / validation string arrays	23 occurrences in 19 files
files declaring a type: 'timeline' node	36
…of those, files carrying any events: key	2 — the declaration in data-display.zod.ts and a refusal probe in timeline-declared-keys.test.ts, neither an authoring
@objectstack/spec 17.4.0: a UI-node events keyed to actions	absent (className occurs 619 times in the same dist)

⚠️ These are figures taken at the ref named above and nothing re-derives them; they will move. The durable claim is the mechanism, not the count: the key is declared by nothing and read by nothing, so whatever is authored under it, no renderer runs it.

The sketch shape is real and in use. It appears on nodes that are not timelines, e.g. a type: 'sidebar-trigger' node in examples/schema-catalog/test/sidebar-trigger-dom-leak-5632.test.tsx, and in DOM-leak sweeps across plugin-dashboard, plugin-chatbot and plugin-calendar — where it is used precisely as an inert canary that must not reach the DOM.

Why it is silent rather than refused

BaseSchemaCore is .passthrough(). An undeclared key is therefore not refused — it stops being judged and the value is KEPT. That is the same mechanism objectui#6124 measured when it refused "the key leaves the mirror" as a remedy for the on* handler keys: a deletion converts a clear parse error into silence. Here there was never a declaration to delete, so the silence is the starting state.

This matters more than an ordinary stale doc because of what the ruled design actually is: handlerKeyRefusal() refuses every on* handler key BY NAME and points the author at the remedy — author behaviour as a node type, an action: node with a declared action, the spelling PR #6498 established. An author who follows AGENTS.md instead writes events and gets no refusal at all, which is strictly worse than the refusal the design went out of its way to provide.

⭐ A second carrier, found while re-measuring. packages/plugin-dashboard/src/DashboardRenderer.tsx carries a docblock stating that "SDUI spells click behaviour events: { onClick }, which is DATA and is dropped by the whitelist". It is prose, not a read — it does not falsify the zero read-site figure — but it repeats the same sketch inside a renderer, while simultaneously confirming the key is dropped. Whoever corrects AGENTS.md should sweep for this belief rather than fix one site.

Scope note

• AGENTS.md is a governed surface (GOVERNED_SURFACES in scripts/check-governed-queue-guard.mjs), so this needs the governed route, not an ordinary drive-by edit.
• Related but not the same defect as objectui#7927 / objectui#8347 (the TypeScript BaseSchema index signature admitting misspelled keys). Those are about an open key set on the TS face; this is about the instruction file publishing a specific key that no face declares and no renderer reads. Removing the index signature would not by itself correct the sketch.
• The direction is not assumed here. Either AGENTS.md describes a design this repo did not build (⇒ correct the sketch and the action-system example), or the design is intended and unimplemented (⇒ a different, larger card). This seat measured the tree; it did not adjudicate which.
• ⛔ The published packages/plugin-dashboard/CHANGELOG.md also contains the spelling. That is historical record and is out of bounds per AGENTS.md [WIP] Update documentation for project #11.

Refs: objectui#6910 · PR #9552 · objectui#6124 (the handler-key ruling) · objectui#5250 (passthrough accepts undeclared keys) · objectui#7927 / objectui#8347.