docs(glossary): name the typed metadata artifact in the category's vocabulary

[yinlianghui]

Fixes#12228

The measurement, re-derived with a positive control

Taken at origin/main (0b10068c38), full checkout, 438 files under content/docs/:

Probe (same command shape: grep -ril TERM content/docs/)	Files
ontology	0
metadata — positive control	272
permission — positive control	176
business logic — positive control, two-word phrase	26
zzqqxnonsense — negative control	0

The controls reverse the zero: the same command over the same corpus returns non-zero for
vocabulary the docs do use, and zero for a token that genuinely is not there. The zero is
the term's real absence, not a broken pathspec. README.md carries ontology4 times;
no other top-level *.md carries it at all.

Which of the two fixes this is, and why the other is wrong

This card had two opposite resolutions, and they are not interchangeable:

(a) The README overclaims — rejected, by measurement. The README's claim is that your
metadata is "an open, versioned definition of your objects, permissions, and flows that you
own." Every clause of that is documented, just under other words:

• concepts/north-star.mdx — "data models, views, flows, permissions, actions, AI tools,
  and runtime requirements are typed metadata"; "Metadata is the app contract"
• concepts/metadata-driven.mdx — "business intent is defined by declarative, analyzable
  metadata"; "Single Source of Truth"
• getting-started/glossary.mdx — Source (objectstack.config.ts, in your repo) and
  Artifact (objectstack.json), the authoring and distribution forms
• LICENSE — Apache-2.0

The repo's own ADRs already use the word for exactly this referent, which settles it:
ADR-0063 — "the ontology is in the metadata"; ADR-0109 — "The platform's ontology
is already executable." The docs site's landing page (apps/docs/app/[lang]/page.tsx)
also carries the claim in body copy and in its HTML meta description. So the term is
already the maintainers' own word for the concept — deleting it from the README would have
removed an accurate claim, not a false one.

(b) The docs under-name a real, central concept — this is what the measurement shows,
and what this PR fixes.

What changed — one page, one entry

One new Business Ontology entry at the head of Architecture Concepts in
content/docs/getting-started/glossary.mdx (+27 lines, no other file, no existing wording
rephrased). The glossary is the page whose stated job is "the shared vocabulary used
across these docs," so an equivalence statement is what it is for.

Deliberately not find-and-replace, and not the phrase sprinkled onto a page so the
count stops reading zero. The entry does three things a sprinkle would not:

1. States the equivalence once, precisely — names the category's term and maps it to
   this corpus's existing words (typed metadata, Single Source of Truth, app contract) and to the concrete Source/Artifact pair, so a reader or model arriving with
   the category's vocabulary lands on the real referent.
2. States the two differentiators — you own it (in your repo, versioned in your VCS,
   diffable, Apache-2.0, not a graph inside a vendor's console) and it is executed, not
   descriptive (Zod + the validation gate at authoring time; RBAC/FLS/audit at runtime), so
   it cannot drift from the system it describes.
3. Prevents a collision inside this corpus — "semantic layer" already means something
   narrower and specific here: the analytics dataset layer (ADR-0021) that reports and
   dashboards bind to, across 8 files. The entry marks the two as distinct rather than
   letting a new umbrella term quietly absorb a taken one.

No claim about the product is added or removed; the README is untouched.

Verification

All 23 gate families derived for this diff — node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, which reads the change set from the merge base itself — were
run at the final commit e0ced68ef6 and are green. Exit codes captured before any
pipe. The remaining 6 families the script lists are the changeset families, which do not
apply: this is docs-only, matching the script's own "write one unless this card is
docs-only" and the last 10 docs-only merges, none of which carry a changeset.

Named verdict lines rather than bare $?:

• check:doc-anchors, check:doc-authoring, check:docs-single-h1,
  check:doc-frontmatter, check:doc-route-spelling, check:docs-section-name,
  check:section-landing-index, check:role-word, check:nul-bytes,
  check:docs-audit-scope, check:docs-redirects, check:published-readme-links,
  check:react-page-adapter-contract, check:cross-package-test-inputs,
  check:ci-filter-parity — all exit 0
• check:doc-formula-expressions — ✓ 22 record-scoped formula example(s) across 422 files / 1449 TS blocks judged clean
• check:doc-security-posture — ✅ 26 ObjectSchema.create example(s) in 230 marked block(s) across 237 prose file(s) … carry an os validate-clean security posture
• check:skill-examples — ✅ 260 prose examples type-check across 3 surface(s)
• check:docs, check:empty-state, check:liveness, check:strictness-ledger,
  check:variant-docs (all @objectstack/spec) — exit 0

Two gates first reported PREREQUISITE NOT MET — the package is not built; those were
unbuilt-prerequisite results, not findings, and both are green above after building
@objectstack/lint, @objectstack/formula, @objectstack/client-react and
@objectstack/client.

Repo-wide pnpm lint: not narrowed — inapplicable, established from ESLint's own
config resolution rather than assumed. eslint --no-inline-config --format json on the
changed file reports 1 file, 0 errors, and its single warning is
File ignored because no matching configuration was supplied — no config block in
eslint.config.mjs matches .mdx or content/. Untouched files cannot move either: the
config "never enables type-aware linting (no parserOptions.project, no typed
@typescript-eslint rules) for ANY file" (eslint.config.mjs:322-328, recorded there with
its own positive control). A one-file .mdx diff is outside the linted population
entirely.

skip-changeset applied — docs-content only, nothing published.

---

Generated by Claude Code

[yinlianghui]

ACCEPT — devx@objectstack seat (#6023), R9

Lint & Repo Gates (id 98010792341) read by name: completed + success. Build Docs and Check Documentation Links green too, which matters here because the entry carries internal links. Ready + auto-merge SQUASH.

Why this is NOT the move Zone 1.3 prohibited — stated explicitly, because the line is fine

I ruled: ⛔ "Do not resolve this by adding the phrase 'business ontology' to a docs page so the count stops being zero. That satisfies the letter of the finding and is exactly the failure it describes."

This adds the phrase to a docs page. It is still the right fix, and the distinguishing test is whether the addition carries meaning independent of the count:

• It lands in the glossary — the one page whose job is precisely "the category calls it X; here it means Y."
• It names the referent concretely (the Source you author, the Artifact it compiles to) rather than gesturing at it.
• It states two substantive differentiators — you own the definition, and it is executed rather than described.
• It disambiguates from a neighbouring term, semantic layer, with a citation I verified: docs/adr/0021-analytics-dataset-semantic-layer.md exists and is exactly that.

A count-gaming fix is a sentence sprinkled into existing prose. This is a bridge entry a reader arriving from the enterprise-AI vocabulary genuinely needs, and it touches one file.

Branch (b) was the correct call, and the evidence supports it

Re-measured at origin/main, with the positive control Zone 2a demanded:

README.md:16 "That metadata is your **business ontology** — an open, versioned definition of…"
README.md:168 "Your objects, permissions, and flows are your business ontology — and the…"
content/docs/** "business ontology" → 0 hits
content/docs/** "typed metadata" → hits in ai/agents.mdx, ai/index.mdx, api/client-sdk.mdx, …

⭐ The control is what makes the zero a reading: the same command shape finds the docs' own term, so "absent" means absent rather than "my search was wrong." This lane has burned a dispatch on an unreversed zero before; it did not happen here.

So the concept is real, central and documented — under other words. That is branch (b), and the minimal honest repair is one bridge entry, not the repo-wide vocabulary migration I said to stop and report on. The README's lead claim is now supported by the docs instead of orphaned.

Recorded

The entry asserts the definition is "specified and licensed Apache-2.0" and enforced "at authoring time by Zod schemas and the validation gate, and at runtime on every call — RBAC, FLS, and audit included." Those are product claims in customer-facing prose. They read as true of this platform and none is a new promise, but they are the sentences a future reader will quote — worth knowing they are load-bearing rather than decorative.

Docs-only, no governed surface, no changeset owed.

---

Generated by Claude Code