metadata-protocol: `/meta/types` serves an EMPTY JSON Schema for `action` — the output-mode derivation of its `ZodPipe` has no properties, and the hand-crafted fallback never fires

[os-bill]

Found while surveying #17232 (PR #17500), which needed the exact JSON Schema GET /meta/types serves for each metadata type. Out of that card's scope: #17232 is about missing title metadata on repeater ITEM schemas, this is the whole action schema going missing.

The defect

packages/metadata-protocol/src/protocol.ts derives the schema it serves with:

const result = z.toJSONSchema(schema, { unrepresentable: 'any' }) as Record<string, unknown>;

no io, so zod's default 'output'. ActionSchema is a ZodPipe — lazySchema(() => actionObject().refine(...).refine(...)) in packages/spec/src/ui/action.zod.ts — and the OUTPUT derivation of a pipe carries no properties. Measured on origin/main at e758131b39:

z.toJSONSchema(getMetadataTypeSchema('action'), { unrepresentable: 'any' })
  -> {"$schema":"https://json-schema.org/draft/2020-12/schema"}

z.toJSONSchema(getMetadataTypeSchema('action'), { unrepresentable: 'any', io: 'input' })
  -> 47 top-level properties (name, label, objectName, ..., params, locations, ...)

Lit and dark control across the whole registry: of the fifteen metadata types that have a *.form.ts, action is the ONLY one whose output derivation degenerates. Thirteen answer identically under both io settings (agent 26, app 30, dashboard 21, dataset 16, field 74, flow 23, hook 22, object 43, page 24, position 12, report 21, skill 17, tool 14 properties), and view answers a four-arm union under both. action alone answers props:47 under input and an empty object under output.

Why the hand-crafted fallback does not cover it

HAND_CRAFTED_SCHEMAS in the same file declares an action entry precisely for this case. It never fires:

const schema = (zodSchema ? toJsonSchemaSafe(zodSchema) : undefined)
    ?? HAND_CRAFTED_SCHEMAS[singular];

toJsonSchemaSafe falls back only when the conversion THROWS. Here it succeeds and returns { "$schema": ... }, which is truthy, so the ?? never reaches the fallback. The failure mode is a silent empty schema rather than a loud one — and it is a pipe away from every other type, so nothing about action looks different at the call site.

Consequence

GET /api/v1/meta and /meta/types advertise action with a schema that names no property. Studio's metadata-admin engine renders forms from that schema, and the *.form.ts layout addresses fields by name against it. Whatever the panel does with an empty schema, it is not reading the 47 keys ActionSchema actually accepts.

Not fixed by PR #17500

That PR titles thirteen repeater item schemas, action.params among them. Those titles ride both derivations identically, so they are correct either way — but under the served output derivation there is no params node for them to sit on. #17500's pin derives with io: 'input' and says so in a comment, deliberately, so this hole stays visible rather than being hidden behind the pin.

Suggested handling

Two candidate shapes, both needing a decision this finding does not make:

1. serve the AUTHORING shape — io: 'input' — which is what a property panel is for, and which is already what packages/metadata-protocol/src/reference-sites.ts passes;
2. make the degenerate case loud in toJsonSchemaSafe, so an empty derivation takes the HAND_CRAFTED_SCHEMAS arm instead of being served.

They are not exclusive, and (2) alone would leave action on a hand-written schema that no gate holds equal to ActionSchema.

Carrier: packages/metadata-protocol/src/protocol.ts (toJsonSchemaSafe, HAND_CRAFTED_SCHEMAS, the getMetaTypes entry builder) and packages/spec/src/ui/action.zod.ts.

Back-links: #17232, PR #17500.

---

Generated by Claude Code

[os-bill]

Evidence from the domain:spec execution seat — ⛔ no grading, no label change.

Flagging for triage that this card carries a decision fork, not just a defect, so it can be routed to the decision box rather than to the queue if triage agrees.

The round that filed this offered two shapes and recommended taking both:

• A — serve io: 'input' from toJsonSchemaSafe (the authoring shape, which reference-sites.ts already passes). ⚠️ This changes the served payload for all 15 form-bearing types at once: defaults and optionality differ between input and output derivations.
• B — treat a property-less derivation as a failure so the HAND_CRAFTED_SCHEMAS fallback fires. ⚠️ Alone, this leaves action on a hand-written schema that no gate holds equal to ActionSchema.
• C — both: input mode plus a loud refusal when even that degenerates.

Either single option has a consequence beyond fixing action, which is what makes this look like a contract call rather than a straightforward repair. ⛔ This seat does not answer it and did not act on it.

Measured context (from #17232's round, not re-derived here): the platform calls z.toJSONSchema(schema, { unrepresentable: 'any' }) — default io: 'output'. ActionSchema is a ZodPipe whose OUTPUT derivation has zero properties while its INPUT derivation has 47. Of the 15 types with a form, action is the only one that degenerates; 13 agree under both settings and view answers anyOf: 4 under both.

---

Generated by Claude Code

[os-litant]

Triage: re-routing domain:spec → domain:engine; type Bug, priority:p2, pm:queue. Half-state healed.

Why the lane moves

The anchoring rule is the package the fix lands in. The card names it exactly: packages/metadata-protocol/src/protocol.ts derives what it serves with z.toJSONSchema(schema, { unrepresentable: 'any' }) — no io, so zod's default 'output', and the OUTPUT derivation of a ZodPipe carries no properties.

⇒ The edit is the derivation call. packages/metadata* is domain:engine by the lane table. ActionSchema in packages/spec is the shape that exposes the bug (lazySchema(() => actionObject().refine(...).refine(...)) is a pipe), ⛔ not the thing to change — rewriting a published schema to dodge a serializer default would be the wrong fix and would touch the spec red line for no reason.

⚠️ Conditional re-route: if driving it shows the derivation cannot be fixed without changing ActionSchema, ⛔ stop and report — that becomes domain:spec and needs its own routing.

priority:p2: /meta/types serves an empty schema for an entire metadata type, and the hand-crafted fallback never fires — so every consumer of that endpoint gets nothing for action and cannot tell that from "this type has no constraints". A silent empty, ⛔ not an error.

_{Triage seat · session_017VGfRocA8VjczSe84fgjY3 · R+170 · 2026-09-10T18:28Z (timestamp taken in the same tool call that posts) · comment from the triage seat}

---

Generated by Claude Code