[finding] the `hook` metadata type's authorable keys reach no key-level ratchet — `HookSchema` emits no JSON Schema, so `authorable-surface/` holds zero `data/Hook:` keys

[claude]

Found by the domain:spec execution seat while implementing #16431 option (c) — the never-published ratchet. Out of scope there by that card's own fence (triage ruled (c) reports what is already true and changes no schema), so it is filed rather than fixed. Unassigned, bare, for triage.

Measured on origin/main @ 142c01c88ee1be4c24e20f7b803a511a00c992fb

hook is a declared metadata type that authors write as documents — packages/spec/src/kernel/metadata-plugin.zod.ts:800:

{ type: 'hook', label: 'Hook', filePatterns: ['**/*.hook.ts', '**/*.hook.yml'],
  supportsOverlay: false, allowOrgOverride: false, allowRuntimeCreate: true, … }

HookSchema emits no JSON Schema. From pnpm --filter @objectstack/spec check:authorable-surface (exit 0 — the skip is a warn):

⊘ Data.HookSchema: Custom types cannot be represented in JSON Schema (skipped)

The unrepresentable member is the deprecated inline-function half of handler, packages/spec/src/data/hook.zod.ts:252:

handler: z.union([z.string(), z.custom<(...args: any[]) => any>(…)]).optional()

What that costs, beyond the missing reference page

Counted in packages/spec/, each with a firing control on the same corpus:

grep -ho '"data/Hook:[^"]*"'        authorable-surface/data.json | wc -l   ->  0
grep -ho '"data/HookContext:[^"]*"' authorable-surface/data.json | wc -l   -> 14   (control)
grep -ho '"data/Object:[^"]*"'      authorable-surface/data.json | wc -l   -> 43   (control)

grep -c '"data/Hook"'        json-schema.manifest/data.json   -> 0
grep -c '"data/HookContext"' json-schema.manifest/data.json   -> 1    (control)

So the authorable keys of a live, author-written metadata type are recorded by no key-level ratchet:

• the authorable-surface ratchet ([P3] Retire the three deprecated aliases — via the ADR-0087 D2 conversion layer, not by deleting the keys #3855 / authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650) has zero data/Hook: keys to compare against, so a renamed or deleted key on HookSchema moves nothing it can see;
• the default-value ratchet (spec 门禁盲区:可作者化 key 的「默认值 / 约束」变更不被任何 gate、tombstone 或 conversion 记录(#4650 / #4659 同族) #4666) measures defaults under the same def keys, so a changed default on HookSchema is likewise outside it;
• the disappearance ratchet (gen:schema silently drops PageTabsProps since #2967 — references regen would delete real docs #2978 / json-schema.manifest.json 的「deliberate removal」删行仍是纪律而非门禁 —— #4650 的同类洞,上移一层(整 schema 级) #4725) cannot help either — data/Hook was never in json-schema.manifest/, which is the state [finding] Five filter operators ($gt/$gte/$lt/$lte/$between) reach NO published reference page — build-schemas.ts skips their whole schema over an unrepresentable z.date(), and the skip is silent #16431 is about.

build-schemas.ts records the mechanism in its own words, in the #4725 block: reachability "is keyed by zodByDefKey, populated only for defs this build EMITS". The measurements above are direct; the mechanism pointer is offered as the likely cause, not as a proof.

Sibling instance, same shape

Data.MemoryConfigSchema — a memory datasource's authorable config — is unprojectable for the same structural reason: exactly one branch of its persistence union ({ type: 'custom', adapter }) carries live functions, while everything an author can write in YAML is representable. Both are now recorded in packages/spec/unemitted-schemas.baseline.json with that reasoning.

Why this is worth a card rather than a passing note

#16431 measured the population (23 exports) and ruled its own remedy scope to the four filter.zod.ts exports whose cause is z.date(). This one has a different cause (z.custom), a different remedy, and a consequence that card does not state: it is not only a documentation gap but a ratchet coverage gap on a metadata type the platform invites authors to write.

A plausible remedy is narrow: the inline-function handler form is already marked DEPRECATED in favour of body, so retiring that union member (ADR-0049 enforce-or-remove, with the ADR-0087 conversion the retirement kit requires) would make HookSchema projectable and pull its keys back under both ratchets. That is a decision, not an edit — hence this card.

Refs: #16431 · #3855 · #4650 · #4666 · #2978 · #4725

---

Generated by Claude Code