metaobjects 0.22.1__tar.gz → 0.23.1__tar.gz

{metaobjects-0.22.1 → metaobjects-0.23.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 0.22.1
+Version: 0.23.1
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects

{metaobjects-0.22.1 → metaobjects-0.23.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.22.1"
+version = "0.23.1"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"

{metaobjects-0.22.1 → metaobjects-0.23.1}/src/metaobjects/codegen/generators/fr019_shared_enum.py

@@ -66,12 +66,21 @@ def resolve_shared_enum_decl(field: MetaField) -> MetaData | None:
 
 
 def is_provided(decl: MetaData) -> bool:
-    """Effective ``@provided`` truth of an enum declaration.
-
-    ADR-0039 — resolves through ``extends`` (``get_meta_attr``): a concrete enum
-    extending an abstract ``@provided`` enum inherits the flag, so an own-only read
-    would misclassify it."""
-    return decl.get_meta_attr(fc.FIELD_ATTR_PROVIDED) is True
+    """``@provided`` truth of an enum DECLARATION.
+
+    ADR-0039 sanctioned own (Python naming inversion: ``attr()`` is the OWN read,
+    ``get_meta_attr()`` resolves). ``@provided`` is a declaration-layer provenance
+    marker — "THIS type is supplied by hand-written/third-party code", like
+    ``is_abstract`` — and does not flow down an ``extends`` chain.
+
+    This is only ever called on the resolved declaration (see
+    ``shared_enum_for_field``), never on the consuming field, so own and resolving
+    agree for a plain ``field extends @provided decl``. They diverge on a CHAINED
+    declaration (root abstract ``B extends`` root abstract ``@provided A``): a
+    resolving read reports B provided and emits a reference to a hand-written ``B``
+    the adopter never declared, instead of materializing B. Matches the JVM ports.
+    """
+    return decl.attr(fc.FIELD_ATTR_PROVIDED) is True
 
 
 def _meta_package_of(decl: MetaData) -> str:

{metaobjects-0.22.1 → metaobjects-0.23.1}/src/metaobjects/core_types.py

@@ -64,13 +64,16 @@ from .meta.core.object.object_constants import (
 from .meta.core.relationship.meta_relationship import MetaRelationship
 from .meta.core.requirement.meta_requirement import MetaRequirement
 from .meta.core.requirement.requirement_constants import (
+    REQUIREMENT_ATTR_DISPOSITION,
     REQUIREMENT_ATTR_IMPLEMENTED_BY,
     REQUIREMENT_ATTR_LEVEL,
     REQUIREMENT_ATTR_STATEMENT,
     REQUIREMENT_ATTR_STATUS,
     REQUIREMENT_ATTR_SUPERSEDED_BY,
+    REQUIREMENT_ATTR_TRACKED_BY,
     REQUIREMENT_ATTR_VERIFIED_BY,
     REQUIREMENT_ATTR_VIOLATION,
+    REQUIREMENT_DISPOSITIONS,
     REQUIREMENT_STATUSES,
     REQUIREMENT_SUBTYPE_ARCHITECTURAL,
     REQUIREMENT_SUBTYPE_FUNCTIONAL,
@@ -589,6 +592,23 @@ _REQUIREMENT_COMMON_ATTRS = [
         required=True,
         allowed_values=REQUIREMENT_STATUSES,
     ),
+    # What was DECIDED about the outstanding work -- a different question from
+    # whether the work is done, which is what @status answers. ABSENT means
+    # UNDECIDED, a real state and the one a review exists to find.
+    AttrSchema(
+        name=REQUIREMENT_ATTR_DISPOSITION,
+        value_type=ATTR_SUBTYPE_STRING,
+        required=False,
+        allowed_values=REQUIREMENT_DISPOSITIONS,
+    ),
+    # Issue/ticket references for outstanding work. Free-form and never resolved:
+    # verify has no network, so unlike @verifiedBy nothing here is checked to exist.
+    AttrSchema(
+        name=REQUIREMENT_ATTR_TRACKED_BY,
+        value_type=ATTR_SUBTYPE_STRING,
+        required=False,
+        is_array=True,
+    ),
     AttrSchema(name=REQUIREMENT_ATTR_STATEMENT, value_type=ATTR_SUBTYPE_STRING, required=True),
     AttrSchema(name=REQUIREMENT_ATTR_VIOLATION, value_type=ATTR_SUBTYPE_STRING, required=True),
     AttrSchema(
@@ -597,6 +617,12 @@ _REQUIREMENT_COMMON_ATTRS = [
         required=False,
         is_array=True,
     ),
+    AttrSchema(
+        name=REQUIREMENT_ATTR_VERIFIED_BY,
+        value_type=ATTR_SUBTYPE_STRING,
+        required=False,
+        is_array=True,
+    ),
     AttrSchema(name=REQUIREMENT_ATTR_SUPERSEDED_BY, value_type=ATTR_SUBTYPE_STRING, required=False),
 ]
 core_provider.add(
@@ -605,14 +631,10 @@ core_provider.add(
         sub_type=REQUIREMENT_SUBTYPE_FUNCTIONAL,
         factory=MetaRequirement,
         attrs=[
+            # REQUIRED on functional: levels are the object-in-focus decomposition
+            # and a functional requirement always sits at one.
             AttrSchema(name=REQUIREMENT_ATTR_LEVEL, value_type=ATTR_SUBTYPE_INT, required=True),
             *_REQUIREMENT_COMMON_ATTRS,
-            AttrSchema(
-                name=REQUIREMENT_ATTR_VERIFIED_BY,
-                value_type=ATTR_SUBTYPE_STRING,
-                required=False,
-                is_array=True,
-            ),
         ],
         child_rules=[
             ChildRule(TYPE_ATTR, "*"),
@@ -626,8 +648,22 @@ core_provider.add(
         type=TYPE_REQUIREMENT,
         sub_type=REQUIREMENT_SUBTYPE_ARCHITECTURAL,
         factory=MetaRequirement,
-        attrs=list(_REQUIREMENT_COMMON_ATTRS),
-        child_rules=[ChildRule(TYPE_ATTR, "*")],
+        attrs=[
+            # OPTIONAL on architectural: absent means a flat, object-independent
+            # policy (the original and still the default form); present opts the
+            # node into a levelled tree, e.g. a quality taxonomy over the
+            # non-functional set. Opt-in precisely so that adding a taxonomy over
+            # existing flat policies cannot invalidate them.
+            AttrSchema(name=REQUIREMENT_ATTR_LEVEL, value_type=ATTR_SUBTYPE_INT, required=False),
+            *_REQUIREMENT_COMMON_ATTRS,
+        ],
+        child_rules=[
+            ChildRule(TYPE_ATTR, "*"),
+            # BOTH subtypes nest. Declaring this on `functional` only was an
+            # omission, not a design: it made an architectural node nestable under
+            # a FUNCTIONAL parent but never under another architectural one.
+            ChildRule(TYPE_REQUIREMENT, "*"),
+        ],
     )
 )
 

{metaobjects-0.22.1 → metaobjects-0.23.1}/src/metaobjects/meta/core/requirement/meta_requirement.py

@@ -9,12 +9,16 @@ from __future__ import annotations
 
 from ...meta_data import MetaData
 from .requirement_constants import (
+    REQUIREMENT_ATTR_DISPOSITION,
     REQUIREMENT_ATTR_IMPLEMENTED_BY,
     REQUIREMENT_ATTR_LEVEL,
     REQUIREMENT_ATTR_STATUS,
+    REQUIREMENT_ATTR_TRACKED_BY,
     REQUIREMENT_ATTR_VERIFIED_BY,
     REQUIREMENT_LINK_FLOOR_LEVEL,
+    REQUIREMENT_STATUS_PLANNED,
     REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES,
+    REQUIREMENT_STATUSES_WITH_OUTSTANDING_WORK,
     REQUIREMENT_SUBTYPE_ARCHITECTURAL,
     REQUIREMENT_SUBTYPE_FUNCTIONAL,
 )
@@ -31,8 +35,9 @@ class MetaRequirement(MetaData):
 
     def level(self) -> int | None:
         """ADR-0039: resolving. 1 solution · 2 segment · 3 service · 4 object ·
-        5 member. Architectural requirements carry none — they are
-        object-independent by definition."""
+        5 member. REQUIRED on functional; OPTIONAL on architectural, where absent
+        means a flat object-independent policy and present opts the node into a
+        levelled tree (e.g. a quality taxonomy over the non-functional set)."""
         v = self.get_meta_attr(REQUIREMENT_ATTR_LEVEL)
         return v if isinstance(v, int) and not isinstance(v, bool) else None
 
@@ -49,19 +54,51 @@ class MetaRequirement(MetaData):
         return [str(x) for x in v] if isinstance(v, list) else []
 
     def verified_by(self) -> list[str]:
-        """ADR-0039: resolving. Names of the tests proving the behaviour."""
+        """ADR-0039: resolving. Names of tests that ASSERT the behaviour — existence
+        evidence only; verify cannot tell whether a named test verifies this."""
         v = self.get_meta_attr(REQUIREMENT_ATTR_VERIFIED_BY)
         return [str(x) for x in v] if isinstance(v, list) else []
 
+    def disposition(self) -> str | None:
+        """ADR-0039: resolving. What was DECIDED about the outstanding work — a
+        different question from whether the work is done, which is what
+        ``status`` answers. ``None`` means UNDECIDED, a real state and the one a
+        review exists to find."""
+        v = self.get_meta_attr(REQUIREMENT_ATTR_DISPOSITION)
+        return v if isinstance(v, str) else None
+
+    def tracked_by(self) -> list[str]:
+        """ADR-0039: resolving. Issue/ticket references for outstanding work.
+        Free-form and NEVER resolved — verify has no network, so unlike
+        ``verified_by`` nothing here is checked to exist."""
+        v = self.get_meta_attr(REQUIREMENT_ATTR_TRACKED_BY)
+        return [str(x) for x in v] if isinstance(v, list) else []
+
+    def is_planned(self) -> bool:
+        """Intended but not built. Its nodes may legitimately not exist yet, and
+        it must NOT count toward object coverage — planning a capability cannot
+        be allowed to silence the warning that nothing implements it."""
+        return self.status() == REQUIREMENT_STATUS_PLANNED
+
+    def has_outstanding_work(self) -> bool:
+        """True when there is outstanding work, so a ``disposition`` says
+        something."""
+        s = self.status()
+        return s is not None and s in REQUIREMENT_STATUSES_WITH_OUTSTANDING_WORK
+
     def may_reference_model(self) -> bool:
         """True when this requirement is permitted to reference the model at all.
-        Architectural requirements always may (their claim set is the point);
-        functional ones only at or below the link floor, so the organisational
-        tiers stay organisational."""
-        if self.is_architectural():
-            return True
+
+        An UNLEVELLED architectural requirement always may — its claim set is the
+        whole point, and that is the original flat form. Once a level is PRESENT
+        the node has opted into a tree, and the link floor applies to it exactly
+        as it does to a functional one, so an "ISO 25010 Security" grouping node
+        cannot quietly start naming entities. Levelling is the opt-in; enforcing
+        the floor unconditionally would have broken every existing flat policy."""
         lvl = self.level()
-        return lvl is not None and lvl >= REQUIREMENT_LINK_FLOOR_LEVEL
+        if lvl is None:
+            return self.is_architectural()
+        return lvl >= REQUIREMENT_LINK_FLOOR_LEVEL
 
     def requires_live_nodes(self) -> bool:
         """True when a dangling ``@implementedBy`` is an ERROR rather than

{metaobjects-0.22.1 → metaobjects-0.23.1}/src/metaobjects/meta/core/requirement/requirement_constants.py

@@ -26,6 +26,8 @@ REQUIREMENT_SUBTYPES = (
 #: 1 solution · 2 segment (app/library) · 3 service · 4 object · 5 member.
 REQUIREMENT_ATTR_LEVEL = "level"
 REQUIREMENT_ATTR_STATUS = "status"
+REQUIREMENT_ATTR_DISPOSITION = "disposition"
+REQUIREMENT_ATTR_TRACKED_BY = "trackedBy"
 REQUIREMENT_ATTR_STATEMENT = "statement"
 REQUIREMENT_ATTR_VIOLATION = "violation"
 REQUIREMENT_ATTR_IMPLEMENTED_BY = "implementedBy"
@@ -35,12 +37,17 @@ REQUIREMENT_ATTR_SUPERSEDED_BY = "supersededBy"
 # ---------------------------------------------------------------------------
 # Status — a closed enum, enforced by the registry via allowed_values.
 # ---------------------------------------------------------------------------
+# Intended but not built. Its references may legitimately dangle, and it never
+# contributes to object coverage -- planning a capability must not silence the
+# warning that nothing implements it.
+REQUIREMENT_STATUS_PLANNED = "planned"
 REQUIREMENT_STATUS_LIVE = "live"
 REQUIREMENT_STATUS_PARTIAL = "partial"
 REQUIREMENT_STATUS_ABANDONED = "abandoned"
 REQUIREMENT_STATUS_SUPERSEDED = "superseded"
 
 REQUIREMENT_STATUSES = (
+    REQUIREMENT_STATUS_PLANNED,
     REQUIREMENT_STATUS_LIVE,
     REQUIREMENT_STATUS_PARTIAL,
     REQUIREMENT_STATUS_ABANDONED,
@@ -59,6 +66,30 @@ REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES = (
 # ---------------------------------------------------------------------------
 # Levels — organisational above the link floor, model-referencing at or below.
 # ---------------------------------------------------------------------------
+# Statuses with outstanding work, so a @disposition is meaningful on them. On any
+# other status the decision IS the status, and recording a second one can only
+# agree with it or contradict it.
+REQUIREMENT_STATUSES_WITH_OUTSTANDING_WORK = (
+    REQUIREMENT_STATUS_PLANNED,
+    REQUIREMENT_STATUS_PARTIAL,
+)
+
+# ---------------------------------------------------------------------------
+# Disposition -- what was DECIDED about the outstanding work. Orthogonal to
+# status, which says whether the work is done. ABSENT means UNDECIDED, and that
+# is the state a review exists to find; collapsing it into the status enum would
+# make "there is a gap" and "we chose to live with it" the same fact.
+# ---------------------------------------------------------------------------
+
+REQUIREMENT_DISPOSITION_ACCEPTED = "accepted"
+REQUIREMENT_DISPOSITION_DEFERRED = "deferred"
+
+# Declaration order is contractual -- see REQUIREMENT_STATUSES.
+REQUIREMENT_DISPOSITIONS = (
+    REQUIREMENT_DISPOSITION_ACCEPTED,
+    REQUIREMENT_DISPOSITION_DEFERRED,
+)
+
 REQUIREMENT_LEVEL_SOLUTION = 1
 REQUIREMENT_LEVEL_SEGMENT = 2
 REQUIREMENT_LEVEL_SERVICE = 3

metaobjects-0.23.1/src/metaobjects/render/payload_accessors.py

@@ -0,0 +1,134 @@
+"""Derived boolean accessors — ``{{#hasFoo}}`` over a payload field ``foo``.
+
+A prompt needs conditional sections ("include the abilities block only when there ARE
+abilities"), and the payload contract answers that with a DERIVED accessor rather than an
+authored boolean field: the author declares ``abilities`` and ``hasAbilities`` follows
+from it. Declaring both would let them disagree.
+
+THE RULE IS SHARED ACROSS PORTS ON PURPOSE. The JVM has carried it since 7.7.7
+(``com.metaobjects.render.PayloadAccessors``, emitted onto every generated payload record
+and accepted by its ``Verify``), and its comment says the emitter and the verifier share
+one rule so they "can never drift apart". Python had neither half, so the same template
+verified clean on the JVM and reported drift here — and rendered WRONG rather than
+failing, silently dropping the section. Gated cross-port by the
+``render-derived-has-accessor`` conformance case.
+"""
+
+from __future__ import annotations
+
+import numbers
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+__all__ = [
+    "HAS_PREFIX",
+    "has_accessor_name",
+    "capitalize",
+    "accessor_value",
+    "with_derived_accessors",
+    "is_boolean_accessor",
+]
+
+#: The ``has`` prefix every derived boolean accessor carries.
+HAS_PREFIX = "has"
+
+_MAX_DEPTH = 32
+
+
+def capitalize(s: str) -> str:
+    """Capitalize the first character, leaving an already-uppercase one untouched.
+
+    Deliberately NOT ``str.capitalize()``, which also lowercases the remainder.
+    """
+    if not s:
+        return s
+    if s[0].isupper():
+        return s
+    return s[0].upper() + s[1:]
+
+
+def has_accessor_name(field_name: str) -> str:
+    """``"has" + capitalize(name)`` (``abilities`` → ``hasAbilities``).
+
+    Byte-identical to the JVM's ``PayloadAccessors.hasAccessorName``.
+    """
+    return HAS_PREFIX + capitalize(field_name)
+
+
+def accessor_value(value: Any) -> bool | None:
+    """Is ``value`` "present" for the purposes of ``has<Field>``?
+
+    Mirrors the JVM emitter's per-type bodies exactly: string → non-null and non-blank;
+    collection → non-null and non-empty; reference → non-null.
+
+    Returns ``None`` for numbers and booleans, which the JVM deliberately emits NO
+    accessor for — they are always-present scalars, and ``{{#hasCount}}`` over an int is
+    drift rather than a conditional. Returning ``None`` (rather than ``False``) keeps that
+    distinction: nothing is injected, so the name stays unresolved exactly as it is on a
+    generated record with no such method.
+    """
+    if value is None:
+        return False
+    if isinstance(value, str):
+        return bool(value.strip())
+    # bool before int — bool IS an int in Python, and a boolean field gets no accessor.
+    if isinstance(value, numbers.Number):
+        return None
+    if isinstance(value, Mapping):
+        return True
+    if isinstance(value, (Sequence, set, frozenset)):
+        return len(value) > 0
+    return True
+
+
+def with_derived_accessors(payload: Any, depth: int = 0) -> Any:
+    """A view over ``payload`` carrying its derived ``has<Field>`` accessors, recursively.
+
+    NON-MUTATING — the caller's payload is never touched, because a render must not be
+    able to change the object it was handed. An AUTHORED key always wins: if a payload
+    genuinely carries ``hasFoo``, that value is kept rather than shadowed.
+
+    Recursion follows Mustache's own scoping: every nested mapping and every sequence
+    ELEMENT becomes a context in its own right, so a section over ``abilities`` sees the
+    accessors of the ability it is currently iterating.
+    """
+    if depth > _MAX_DEPTH:
+        return payload  # pathological graph; render is not a validator
+    if isinstance(payload, Mapping):
+        out: dict[str, Any] = {
+            k: with_derived_accessors(v, depth + 1) for k, v in payload.items()
+        }
+        for k, v in payload.items():
+            if not isinstance(k, str):
+                continue
+            name = has_accessor_name(k)
+            if name in payload:  # authored wins
+                continue
+            derived = accessor_value(v)
+            if derived is not None:
+                out[name] = derived
+        return out
+    if isinstance(payload, (str, bytes)):
+        return payload
+    if isinstance(payload, Sequence):
+        return [with_derived_accessors(v, depth + 1) for v in payload]
+    return payload
+
+
+def is_boolean_accessor(stack: list[list[Any]], name: str) -> bool:
+    """True when ``name`` is a derived accessor over a field reachable on ``stack``.
+
+    Mirrors the JVM's ``Verify.isBooleanAccessor``, including its deliberate
+    permissiveness: acceptance keys off the FIELD EXISTING, not off its type. Accessors
+    are simple (undotted) names; a dotted path is never an accessor.
+    """
+    if "." in name:
+        return False
+    if not name.startswith(HAS_PREFIX):
+        return False
+    # Mustache outward walk (innermost → outermost).
+    for frame in reversed(stack):
+        for f in frame:
+            if name == has_accessor_name(f.name):
+                return True
+    return False

{metaobjects-0.22.1 → metaobjects-0.23.1}/src/metaobjects/render/renderer.py

@@ -23,6 +23,7 @@ from dataclasses import dataclass, field
 from typing import Any
 
 from . import escapers
+from .payload_accessors import with_derived_accessors
 from .verify import InMemoryProvider, Provider
 
 MAX_DEPTH = 32
@@ -59,7 +60,10 @@ def render(req: RenderRequest) -> str:
     _validate(req)
     body = req.template if req.template is not None else _resolve_or_raise(req.provider, req.ref)
     expanded = _pre_expand_partials(body, req.provider, [])
-    out = _interpret(expanded, req.payload, req.format)
+    # Derived `has<Field>` accessors are part of the payload contract, not of the
+    # caller's object — see payload_accessors. Injected here so a `{{#hasFoo}}` section
+    # resolves the same way it does against a generated JVM payload record.
+    out = _interpret(expanded, with_derived_accessors(req.payload), req.format)
     # @maxChars is a fail-closed render budget: over-budget output RAISES (never
     # silently truncates). Canonical cross-port behavior — message shape matches
     # TS/C#/Java: "render exceeded maxChars budget: <len> > <cap>".

{metaobjects-0.22.1 → metaobjects-0.23.1}/src/metaobjects/render/verify.py

@@ -23,6 +23,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Protocol
 
+from .payload_accessors import is_boolean_accessor
+
 #: A ``{{var}}`` references a field the (contextual) payload does not declare.
 ERR_VAR_NOT_ON_PAYLOAD = "ERR_VAR_NOT_ON_PAYLOAD"
 #: A ``{{> ref}}`` partial does not resolve in the provider.
@@ -215,7 +217,9 @@ def verify(
                     continue  # implicit iterator — always valid
                 if at_root:
                     referenced_at_root.add(tok.value.split(".")[0])
-                if _resolve(stack, tok.value) is None:
+                if _resolve(stack, tok.value) is None and not is_boolean_accessor(
+                    stack, tok.value
+                ):
                     errors.append(VerifyError(ERR_VAR_NOT_ON_PAYLOAD, tok.value))
             elif isinstance(tok, _Section):
                 if tok.value == ".":
@@ -225,6 +229,12 @@ def verify(
                     referenced_at_root.add(tok.value.split(".")[0])
                 field = _resolve(stack, tok.value)
                 if field is None:
+                    # A derived `has<Field>` gate is a BOOLEAN over the current context:
+                    # it resolves nothing and pushes nothing, so walk the body in the SAME
+                    # scope — what `{{#hasAbilities}}{{#abilities}}…` depends on.
+                    if is_boolean_accessor(stack, tok.value):
+                        walk(tok.children, stack, seen)
+                        continue
                     # Unresolved section head is itself drift; skip the body (its
                     # context is unknowable, walking it would cascade false errors).
                     errors.append(VerifyError(ERR_VAR_NOT_ON_PAYLOAD, tok.value))

{metaobjects-0.22.1 → metaobjects-0.23.1}/src/metaobjects/spec_metamodel/documentation.json

@@ -12,7 +12,7 @@
           "name": "description",
           "min": 0,
           "max": 1,
-          "description": "Free-form user-facing prose. Markdown allowed, multi-line via YAML '|' block scalar. Flows into doc-gen surfaces (JSDoc / XML-doc / Postgres COMMENT / Mermaid prose)."
+          "description": "What this element IS and COVERS, written for someone using it. Markdown allowed, multi-line via YAML '|' block scalar. Flows into doc-gen surfaces (JSDoc / XML-doc / Postgres COMMENT / Mermaid prose). State scope and boundary — what it covers, what it deliberately does NOT, and which sibling owns the rest — all of which is derivable from the model itself. Anything you had to read the implementation to learn belongs in @notes, not here."
         },
         {
           "type": "attr",
@@ -20,7 +20,7 @@
           "name": "summary",
           "min": 0,
           "max": 1,
-          "description": "Short single-line tagline (OpenAPI `summary` pattern) — used in index tables, sidebar previews, and AI prompts where the full @description is too long. Optional supplement to @description; when @summary is unset, doc surfaces typically fall back to the first sentence of @description."
+          "description": "Short single-line SENTENCE (OpenAPI `summary` pattern) — used in index tables, sidebar previews, and AI prompts where the full @description is too long. Distinct from @title, which is a noun label rather than a sentence. When @summary is unset, doc surfaces typically fall back to the first sentence of @description."
         },
         {
           "type": "attr",
@@ -28,7 +28,7 @@
           "name": "title",
           "min": 0,
           "max": 1,
-          "description": "Short single-line human label (e.g. 'Email' for a `field.string email`). Optional supplement to description."
+          "description": "Short single-line human label — a NOUN PHRASE naming the element (e.g. 'Email' for a `field.string email`), never a sentence. What a tab, an index row or a sidebar shows when the name is an identifier rather than a label. See @summary for the one-line sentence form."
         },
         {
           "type": "attr",
@@ -36,7 +36,7 @@
           "name": "notes",
           "min": 0,
           "max": 1,
-          "description": "Internal-only rationale. Stays in metadata; never emitted to user-facing docs."
+          "description": "Internal-only rationale, never emitted to user-facing docs — the slot for what you had to look OUTSIDE the model to learn: evidence, measurements, citations, the control that proved an absence was real, and what breaks if this changes. It is NOT a longer @description, and restating the description here is the failure mode this slot invites. Mechanical test: a sentence belongs in @notes exactly when it would have to change because the IMPLEMENTATION changed while the model did not."
         },
         {
           "type": "attr",