D1: declare the metadata item-name grammar in spec and refuse it loudly at the publish door — dotted qualified form becomes enforced (#12176 stage 1)

[os-trump]

Stage 1 of #12176's maintainer-ruled retirement of compound-name addressing. Filed and dispatched by the PM session under the maintainer direct-dispatch channel; provenance (verbatim, untranslated): 「我认为斜杠不该存在」 · 「斜杠不该存在，现在就立卡，你负责派发，然后给我结果」, and the Q2 fork (dotted form) presented with four-axis analysis and accepted: 「我看到你的意见了，我同意」 (Q2 = B). PM session session_01H9StxQgG2DPA26XzZZqnJB.

Ruled scope

1. Declare the item-name grammar in packages/spec: item names are lowercase snake_case segments, optionally dot-qualified — the shape ViewItemNameSchema already declares (crm_lead.pipeline). ⛔ Reuse/extend that existing declaration as the single source; do not mint a second grammar. Exact regex is the implementer's to derive from it (expected family: /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/), with the boundary cases decided by the declaration, not ad hoc: no /, no empty string, no whitespace, no uppercase, no leading/trailing/double dots.
2. Enforce it at the publish door (packages/metadata-protocol — the publishMetaItem/store write path): a name failing the grammar is refused loudly with guidance naming the grammar and the dotted qualified form. This deliberately widens refuseUnmintableMetaType's refusal: Ban / in metadata item names — retire compound-name addressing (maintainer-ruled direction): census, migration surface, staged plan #12176's census measured that a slash in the name currently BYPASSES the unrecognised-type refusal (type=fieldz, name='a/b' accepted and stored while name='a' is 400) — that hole closes here.
3. Landing assert (absorbed D2): census measured zero stored rows with / in the name; assert that at land time against the seeded stores. If any slash row exists after all, ⛔ do not migrate silently — report it (that is D2 reopening as its own card).
4. ADR-0087 semantic entry + changeset stating the narrowing and what an author must write instead.

Premise (binding — verify before landing the regex)

The dotted convention's existing corpus is coherent: census the stored/seeded/authored item names for dot usage and confirm the declared ViewItemNameSchema grammar accepts every legitimate existing name (flat snake_case included) while refusing the junk shapes ('', a//b, 'Views/All Leads' — all measured accepted today). If a legitimate existing name class fails the declared grammar, ⛔ stop and report the fork with the census — do not widen the grammar unilaterally and do not exclude the class silently.

Out of scope

⛔ REST/SDK re-addressing and compound-route retirement (D3, blocked on this card). ⛔ Docs sweep (D4). ⛔ Do not touch the mounted compound routes or SDK URL construction. ⛔ No edits to what closed PR #12105 contained.

Clause-②: yes — contract narrowing (accept set shrinks at the publish door); dispatch at the contract-review tier. Serial note at claim: packages/spec has in-flight work on component.zod.ts + migrations/registry.ts (#12039 Key 1 landing) — registry entries are per-file tail-append with regeneration, different files; name the check in the claim.

Refs: #12176 (census report with the four tables and staged plan) · #12106, #11932 (parked behind D3) · closed PR #12105.

[os-trump]

Claim: maintainer direct-dispatch (2026-08-25 PM chat session, chain stage D1)
Session: session_01H9StxQgG2DPA26XzZZqnJB
Branch: claude/issue-12194-item-name-grammar
Worktree: objectstack-issue-12194
Domain: direct-dispatch (spec-lane surface — packages/spec + packages/metadata-protocol; suggested domain:spec for triage record)
File surface: packages/spec/src/** (item-name grammar beside/extending ViewItemNameSchema; ADR-0087 semantic entry + regenerated registry; changeset) + packages/metadata-protocol/src/protocol.ts (publish-door refusal) + their tests (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: claude-fable-5 — Clause-② content leg (contract accept-set narrowing) ⇒ contract-review tier mandatory
Clause-②: yes
Serial constraints cleared: packages/spec in-flight = #12039 Key 1 (component.zod.ts + migrations/registry.ts tail-append; PR #12120) — different files; registry entries are per-file with regeneration (conflict-free by construction, re-run gen:migration-registry after any merge of main). No in-flight claim touches metadata-protocol/src/protocol.ts per the current board. No pin asserts sibling behavior.

Direct-dispatch audit (who / verbatim / where): the maintainer, PM chat session 2026-08-25: 「斜杠不该存在，现在就立卡，你负责派发，然后给我结果」; Q2 fork accepted 「我看到你的意见了，我同意」 (dotted qualified form becomes enforced).

---

Generated by Claude Code

[os-trump]

os-dev-report

{
 "issue": 12194,
 "status": "done",
 "branch": "claude/issue-12194-item-name-grammar",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12244",
 "premise_still_valid": true,
 "summary": "Grammar declared in spec from ONE segment source and enforced at the publish door; the slash bypass is closed. shared/identifiers.zod.ts declares METADATA_ITEM_NAME_PATTERN (lowercase snake_case segments, optionally dot-qualified — the card's regex family) and MetadataItemNameSchema, with ViewItemNameSchema re-derived from the same ITEM_NAME_SEGMENT (its dot-REQUIRED arity, behavior byte-identical) — no second grammar minted; SaveMetaItemRequestSchema.name and PublishMetaItemRequestSchema.name carry it. refuseUngrammaticalMetaItemName runs in saveMetaItem AND publishMetaItem before the store-backed type probe, answering 400 INVALID_REQUEST with the grammar + dotted prescription; refuseUnmintableMetaType's slash exemption is DELETED (its documented 'PUT /meta/fieldz/a/b accepted' residue closes; anti-vacuity pinned: fieldz + grammatical name still earns the TYPE refusal). Enforcement sites bound, traced not assumed: all REST writes (single + compound folds in rest-server.ts) and dispatcher writes (runtime/domains/meta.ts folds) reach protocol.saveMetaItem; publishPackageDrafts/rollbackMetaItem/duplicatePackage operate on stored rows the closed save door keeps grammatical; migrateStoredMetadata is deliberately NOT exempt — an off-grammar stored row's rewrite records a loud per-row outcome:'failed' with this refusal's text on the migrate report, never silent. Reads and deleteMetaItem stay open for residue (pinned). PREMISE VERIFIED FIRST, HOLDS: 146 authoring-file item names + 68 define-call names censused against the regex BEFORE landing it — 0 failures; dotted legit names (showcase.export_data, auth.password_reset, ping.body) all fit; junk/accept controls both fired. ONE QUALIFICATION reported, not smoothed: TranslationItemSchema documents translation items 'conventionally named after their locale (zh-CN)' and authored-translation-sync's LOCALE_LIKE tolerates dashed/uppercase STORED names on the read side; zh-CN fails the grammar (uppercase + dash — boundary cases the card itself rules out). Measured at ZERO in-repo addressing-name occurrences outside one org-scope test fixture (respelled zh_cn in this PR; locale keeps 'zh-CN' — it is the type's REQUIRED identity, so no capability is lost and dashed residue rows still read). If locale-named rows are load-bearing in out-of-repo deployments, that is D2 reopening. LANDING ASSERT (absorbed D2) HOLDS at the final commit f6cb548c: stored slash rows ZERO — JSON-corpus slash-name hits are npm package.json names only beside a 460-file positive control; authored slash name: literals 0; all 11 non-test compound-specimen literals are docs/SDK/fold prose (D3/D4 surface). ADR-0087 semantic entry metadata-item-name-grammar-enforced + minor changeset carrying the registered marker. origin/main merged twice; the second merge brought #12039 Key 1 — both semantic:18 entries verified present after gen:migration-registry, and the ADR-0122 pin-count conflict resolved semantically (main's -1 + this branch's +1 = 835, verified by recount). Out of scope untouched: compound routes, SDK URL construction, docs pages, PR #12105 content.",
 "tests": "Premise census FIRST (scripted, before the regex landed): 146 authoring-file item names + 68 define-call names, 0 grammar failures; junk control 'OK — all refused', accept control 'OK — all accepted'. RED-BEFORE-FIX on origin/main@22c42c9b sources via restore-under-trap: mutation proven on disk (guard refs 0 / pattern 0 / wiring 0 / derivation 0 — four greps, all 0), spec rebuilt at BASE 'spec build exit: 0', dist proof 0 (marker absent from dist); vitest 'Test Files 2 failed (2) / Tests 19 failed | 24 passed (43)', 18 failures carrying the 'promise resolved' acceptance signature — the census P2–P8 junk acceptances and the P10 slash-bypass acceptance reproduced, accept-side green. FIRST red attempt VOIDED and redone, stated per discipline: the fixed tree's json-schema.manifest shard blocked the BASE rebuild (build exit 1, dist proof 6, not 0) so that run's readout was discarded and the manifest added to the restore set. GREEN leg: trap-restored fix (markers 5/4), spec rebuilt, dist marker present (grep 3 in dist/shared/index.js), 'Tests 43 passed (43)', VITEST_EXIT=0. UNION at the final head — run echoes 'UNION HEAD: f6cb548c': metadata-protocol FULL 'Test Files 140 passed | 2 skipped (142) / Tests 1944 passed | 10 skipped (1954)'; triaged rest files 'Tests 49 passed (49)'; triaged runtime files 'Tests 25 passed (25)'; spec pin/migrations/export-origins/root-index 'Tests 150 passed (150)'; 'EXITS: mp=0 rest=0 runtime=0 spec=0'; typecheck spec+metadata-protocol+rest+runtime 'os-verify-lock: VERDICT command-exit 0'. Full-suite triage runs along the way: rest 'Test Files 146 passed (146)', runtime 188 files green after triage, spec 426 files green after artifact regen. DERIVED GATES from 'node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack' (stderr provenance: \"gate list derived from the tree of 'objectstack-ai/objectstack' at commit f6cb548c\"): 38/38 PASS, '=== gate summary: 0 failed ===' with 'os-verify-lock: VERDICT command-exit 0' — including check:generated 14/14 after regen, check:adr-0087-registration ('each carrying an ADR-0087 disposition ... registered metadata-item-name-grammar-enforced'), check:spec-parsed-alias ('835 pinned isomorphic ... OK' post-merge), check:engine-double-contract after --write ('392 (file, verb) row(s) held'), and check:type-check-debt re-measure over the fully built closure ('32 ledger entr(ies) re-measured ... none above its recorded number'). All exits captured before any pipe (redirect-then-capture), verdicts quoted from each gate's own printed line. Lock-discipline note the lock itself asked to be stated on the card: the final 38-gate roster held the shared verify lock 17m26s in one run (its long-holder warning fired) — a one-off land-time union of the whole derived roster, not a recurring shape; every other run held ≤7m.",
 "open_questions": [],
 "out_of_scope_findings": ["filed as #12245: SystemIdentifierSchema/EventNameSchema (shared/identifiers.zod.ts) still declare the character-class dotted grammar that admits the empty-segment shapes the item-name grammar refuses (a., a..b, trailing dots) across object/field/role/event/app-id surfaces — observation-class, finding label, needs per-surface corpus censuses before any narrowing"]
}

---

Generated by Claude Code