Skip to content

[finding] five defineStack({ manifest: … }) doc snippets are refused at their own door for want of an elision marker their 7 siblings carry — a docs-convention ruling, not a repair #18777

Description

@os-support-ai

Surfaced by the dev delivering #18607 (PR #18771), found only because its duplicate sweep's predicate was about the manifest SHAPE rather than about the call name — a packages.install-shaped search would have missed all five. ⛔ Filed bare: finding only; grading and domain:* are triage's.

The five sites

Each writes a defineStack({ manifest: … }) snippet with some keys and no elision marker, so a reader copying the block gets a refusal. Re-driven at the real door (ObjectStackDefinitionSchema), with the manifest-scoped codes:

site literal refused on
content/docs/kernel/services-checklist.mdx:473 {id,namespace} invalid_type[manifest,version] · invalid_value[manifest,type] · invalid_type[manifest,name]
content/docs/permissions/authorization.mdx:176 {namespace} invalid_type[manifest,id] · invalid_type[manifest,version] · invalid_value[manifest,type] · invalid_type[manifest,name]
content/docs/permissions/capabilities.mdx:103 {name,namespace,version} invalid_type[manifest,id] · invalid_value[manifest,type]
content/docs/permissions/record-view-auditing.mdx:86 {name,version} invalid_type[manifest,id] · invalid_value[manifest,type]
docs/design/marketplace-publishing.md:398 {id,type,namespace,version} invalid_type[manifest,name]

⭐ Why this is a RULING and not a repair — and why it is filed apart from its sibling

The sibling card (the client-sdk.mdx install example) has one obviously-correct repair. These five do not, and the difference is the reason they are not one card: a single card would let the easy half carry the hard half.

⚠️ Stated as judgement, ⛔ not as a reading: the same corpus writes an explicit elision in 7 other places — content/docs/data-modeling/import-mappings.mdx:49, object-extensions.mdx:47, deployment/cli.mdx:361, plugins/index.mdx:177, protocol/kernel/http-protocol.mdx:1078, packages/mcp/README.md:440 (all manifest: { /* … */ }), and packages/services/service-package/README.md:40 (/* …full ObjectStackManifest… */). Those 7 are declared partials and therefore NOT findings. It is that convention existing next door which makes these five read as omissions rather than as declared partials.

⇒ the open question is a docs convention: does a one-feature snippet owe a complete manifest, or an elision marker? Either answer is defensible and ⛔ neither is a dev's or this seat's to pick:

  • complete the manifest at all five — verbose, but every block then parses;
  • mark them elided like their 7 siblings — cheap, and keeps the snippet's focus.

⛔ Not asserted

That either remedy is right, and that the 7 elided literals need anything. ⛔ Also not asserted that this belongs to the same lane as its sibling — the sibling is one broken example; this is a convention across two docs trees.

Dedupe words: defineStack manifest snippet incomplete · docs manifest missing id type · ObjectStackDefinitionSchema refuses doc example · elision marker missing manifest · permissions docs defineStack manifest.

Dedupe run before filing: complete repo-scoped enumeration of 517 open issues (⚠️ REST /search/* is 403 for this seat, so enumeration + local match). defineStack → 9, elision → 1, ObjectStackDefinitionSchema → 5; none names this class. Negative control → 0.


_Generated by Claude Code


Generated by Claude Code

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions