metaobjects 0.22.1__tar.gz → 0.23.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 0.22.1
+Version: 0.23.0
 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.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.22.1"
+version = "0.23.0"
 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.0}/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.0}/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
 
@@ -53,15 +58,46 @@ class MetaRequirement(MetaData):
         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.0}/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.22.1 → metaobjects-0.23.0}/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",

metaobjects-0.23.0/src/metaobjects/spec_metamodel/requirement.json

@@ -0,0 +1,209 @@
+{
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "requirement",
+      "subType": "functional",
+      "description": "What the product does for a user, stated as one violable claim. Its check is EXISTENCE: it fails when nothing implements it. Hierarchy is nesting — an L1 solution contains its L2 segments, which contain L3 services, and so on down to the levels that reference the model.",
+      "whenToUse": "Something exists because someone asked for it. L1-L3 are levels of ABSTRACTION AND OWNERSHIP in the problem domain — whose need is this, and at what altitude — and are never a directory, package, deployable or module. Binding to technical constructs happens only at L4 (an object) and L5 (a member), which is the allocation step. Test every node: if a refactor that changes no behaviour would force it to move, its level is wrong.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "level",
+          "min": 1,
+          "max": 1,
+          "description": "1 solution, 2 segment, 3 service, 4 object, 5 member. L1-L3 are levels of abstraction and ownership in the problem domain, NOT of code structure. Nesting depth must agree with it; skipping a level is legal, going back up is not."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "status",
+          "min": 1,
+          "max": 1,
+          "allowedValues": [
+            "planned",
+            "live",
+            "partial",
+            "abandoned",
+            "superseded"
+          ],
+          "description": "planned intended but not built yet; live implemented and in use; partial implemented with known gaps; abandoned built then deliberately retired; superseded replaced by a different mechanism. A dangling @implementedBy is an ERROR on live/partial (the model moved, the requirement is stale) and ALLOWED on planned/abandoned/superseded — on planned the nodes do not exist YET, on the other two they are meant to be gone, and that is the entry doing its job. A planned requirement also never contributes to object coverage: planning a capability must not silence the warning that nothing implements it."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "disposition",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "accepted",
+            "deferred"
+          ],
+          "description": "What has been DECIDED about outstanding work — a different question from whether the work is done, which is what @status answers. accepted: the gap is understood and deliberately not being closed. deferred: it will be closed, but not now. ABSENT MEANS UNDECIDED, which is a real and useful state — it is what an unreviewed gap looks like, and it is the one a review should be able to find. Meaningful on planned and partial only; on a status with no outstanding work it is a WARNING. Deliberately NOT a workflow vocabulary: which sprint, who owns it and whether it is in progress belong in the tracker named by @trackedBy, because two systems holding that answer will drift and only one of them is refreshed daily."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "trackedBy",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Issue or ticket references for outstanding work — a URL, an owner/repo#123 shorthand, or a tracker key. Free-form and NOT resolved by verify, which does not reach the network; unlike @verifiedBy, nothing here is checked to exist. Its job is to stop a deferred gap becoming invisible, so verify warns when a deferred requirement names no ticket. Also the right place to link the ticket that a planned requirement will be built under."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "statement",
+          "min": 1,
+          "max": 1,
+          "description": "What the capability is, in one sentence."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "violation",
+          "min": 1,
+          "max": 1,
+          "description": "What breaking it looks like, in one sentence. A requirement MUST be violable: 'every entity has a uuid primary key' is (point at one with a composite string key); 'things are persisted' is not, and is a description rather than a requirement."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "implementedBy",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "FQN references to the model nodes realising this requirement. Legal on level 4 (an object) and level 5 (a field, view or identity) only; an organisational level carrying it is ERR_REQUIREMENT_LINK_ABOVE_FLOOR. Many-to-many by construction — several requirements may name the same node."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "verifiedBy",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Names of the tests proving the behaviour. verify checks each exists and is not skipped; it never runs them."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "supersededBy",
+          "min": 0,
+          "max": 1,
+          "description": "The requirement that replaced this one. Expected on status=superseded."
+        },
+        {
+          "type": "requirement",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null,
+          "description": "Nested child requirements. Hierarchy IS nesting — an L1 solution contains its L2 segments, which contain L3 services — so regrouping moves a node rather than editing a parent string, and a requirement is addressable by the same dotted child-name path as every other node."
+        }
+      ]
+    },
+    {
+      "type": "requirement",
+      "subType": "architectural",
+      "description": "How the system is built, applied uniformly across the model. Its check is UNIVERSALITY: it fails when something VIOLATES it, which is the opposite polarity to a functional requirement. Flat by default and object-independent; it may optionally sit in a levelled tree when a quality taxonomy is being used to organise non-functional requirements.",
+      "whenToUse": "Something exists because every entity here looks like this — a uuid primary key, an @autoSet createdAt, a change-attribution column, tenant scoping. The discriminator is mechanical: did this exist because someone asked for something, or because it is the architecture? For a non-functional tree, an established quality taxonomy makes a good fixed upper structure (e.g. an ISO/IEC 25010 characteristic at L1, its sub-characteristic or a control-catalogue category at L2), with the model-binding claims at L4 and L5 as usual.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "level",
+          "min": 0,
+          "max": 1,
+          "description": "OPTIONAL here, unlike on a functional requirement where it is required. ABSENT means a flat, object-independent policy that may reference the model directly — the original and still the default form. PRESENT means this node sits in a levelled tree, and then the same rules as functional apply: nesting must agree with the level, and only L4/L5 may carry @implementedBy. Levelling is opt-in so that adding a taxonomy on top of existing flat policies does not invalidate them."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "status",
+          "min": 1,
+          "max": 1,
+          "allowedValues": [
+            "planned",
+            "live",
+            "partial",
+            "abandoned",
+            "superseded"
+          ],
+          "description": "As on requirement.functional. A live or partial architectural requirement claimed by NOTHING is an error: a policy declared and applied to nothing. A planned one is exempt from that check — it is not applied yet by definition."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "disposition",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "accepted",
+            "deferred"
+          ],
+          "description": "As on requirement.functional. On an architectural requirement, accepted is the common and important case: a policy that is genuinely not universal, where the exceptions are known and tolerated, is more honest as partial+accepted than as a live claim nobody audits."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "trackedBy",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "As on requirement.functional. Issue or ticket references for outstanding work; free-form, not resolved."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "statement",
+          "min": 1,
+          "max": 1,
+          "description": "The policy, in one sentence."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "violation",
+          "min": 1,
+          "max": 1,
+          "description": "What breaking it looks like — the node that would contradict it. This is what makes universality checkable."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "implementedBy",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "FQN references to the nodes applying this policy. High fan-out is normal and expected: one uuid-primary-key requirement is claimed by every entity."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "verifiedBy",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Names of the tests proving the policy holds. verify checks each exists and is not skipped; it never runs them."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "supersededBy",
+          "min": 0,
+          "max": 1,
+          "description": "The requirement that replaced this one. Expected on status=superseded."
+        },
+        {
+          "type": "requirement",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null,
+          "description": "Nested child requirements. Present so a non-functional tree can be organised by a quality taxonomy the same way a functional tree is organised by capability — the absence of this rule, while requirement.functional had it, is what previously made an architectural node nestable UNDER a functional one but never under another architectural one."
+        }
+      ]
+    }
+  ]
+}

{metaobjects-0.22.1 → metaobjects-0.23.0}/tests/integration/postgres_container.py

@@ -42,6 +42,9 @@ class PostgresContainer:
     """Context manager around ``docker run`` for a per-scenario Postgres."""
 
     IMAGE = "postgres:16-alpine"
+
+    #: Fresh-port retries before giving up -- see the port-race note in __init__.
+    START_ATTEMPTS = 3
     USER = "postgres"
     PASSWORD = "test"
     DATABASE = "postgres"
@@ -57,19 +60,45 @@ class PostgresContainer:
         self._shared = False
         self._admin_url = None
         self._name = f"metaobjects-test-{uuid.uuid4().hex[:8]}"
-        self._port = _pick_free_port()
-        self._info = PostgresInfo(
-            host="localhost", port=self._port, database=self.DATABASE,
-            user=self.USER, password=self.PASSWORD,
-        )
-        _docker(
-            "run", "-d", "--rm",
-            "--name", self._name,
-            "-e", f"POSTGRES_PASSWORD={self.PASSWORD}",
-            "-p", f"{self._port}:5432",
-            self.IMAGE,
+        # PORT RACE. _pick_free_port() closes its probe socket and hands the number to
+        # docker, which binds it LATER -- a check-then-act gap. Alone it never bites;
+        # under a full CI run several ports start containers at once and two can be
+        # handed the same number. The loser's container is created and then dies, and a
+        # readiness probe that only asks `docker exec` cannot tell that from a slow
+        # boot. Retry on a FRESH port.
+        #
+        # Deliberately NOT `--rm`: an auto-removed container takes its logs with it, so
+        # the one artefact explaining the failure vanishes exactly when it is needed.
+        # close() force-removes, so nothing leaks.
+        last_failure: Exception | None = None
+        for _attempt in range(self.START_ATTEMPTS):
+            self._port = _pick_free_port()
+            self._info = PostgresInfo(
+                host="localhost", port=self._port, database=self.DATABASE,
+                user=self.USER, password=self.PASSWORD,
+            )
+            try:
+                _docker(
+                    "run", "-d",
+                    "--name", self._name,
+                    "-e", f"POSTGRES_PASSWORD={self.PASSWORD}",
+                    "-p", f"{self._port}:5432",
+                    self.IMAGE,
+                )
+            except Exception as e:  # noqa: BLE001 — docker refused the bind; retry on a new port
+                last_failure = e
+                self._force_remove()
+                continue
+            try:
+                self._wait_ready()
+                return
+            except Exception as e:  # noqa: BLE001 — died on startup; retry on a new port
+                last_failure = e
+                self._force_remove()
+        raise RuntimeError(
+            f"postgres container '{self._name}' failed to start in "
+            f"{self.START_ATTEMPTS} attempts; last err: {last_failure}"
         )
-        self._wait_ready()
 
     # -- Shared-sidecar mode -------------------------------------------------
     # CREATE a fresh, uniquely-named database on the already-running Postgres
@@ -138,11 +167,50 @@ class PostgresContainer:
     # finishes; mirrors the TS/Java two-phase wait).
     # -----------------------------------------------------------------------
 
+    # READINESS WINDOW. 30s was too tight: under a FULL local-CI run several ports
+    # spin their own Postgres concurrently, and a container that is merely slow to
+    # boot produces a red gate indistinguishable from a real failure -- it fires
+    # BEFORE any test logic. Raising the bound costs nothing when the container is
+    # ready quickly (the loop polls every 250ms and returns immediately) and only
+    # changes how long the pathological case takes to give up.
+    def _force_remove(self) -> None:
+        """Best-effort teardown between start attempts."""
+        try:
+            _docker("rm", "-f", self._name)
+        except Exception:  # noqa: BLE001 — already gone
+            pass
+
+    def _inspect_state(self) -> str:
+        """The container's docker state, or 'gone' when it cannot be determined."""
+        r = subprocess.run(
+            ["docker", "inspect", "-f", "{{.State.Status}}", self._name],
+            capture_output=True, text=True,
+        )
+        return r.stdout.strip() if r.returncode == 0 else "gone"
+
+    def _tail_logs(self) -> str:
+        """Last few log lines, for an error that would otherwise name only a symptom."""
+        r = subprocess.run(
+            ["docker", "logs", "--tail", "40", self._name], capture_output=True, text=True,
+        )
+        return (r.stdout + r.stderr).strip() if r.returncode == 0 else "(docker logs unavailable)"
+
     def _wait_ready(self) -> None:
         import pg8000.dbapi  # local import — pg8000 lives in the `integration` extra
-        deadline = time.monotonic() + 30
+        timeout_s = int(os.environ.get("MO_PG_READY_TIMEOUT_S", "120"))
+        deadline = time.monotonic() + timeout_s
         last_err: Exception | None = None
         while time.monotonic() < deadline:
+            # FAIL FAST ON A DEAD CONTAINER. `docker exec` alone cannot tell "still
+            # booting" from "exited seconds ago" -- both just fail -- so a container that
+            # died on startup used to burn the whole window and report a TIMEOUT, which
+            # reads as slowness and is not. Ask docker for its state and surface its logs.
+            state = self._inspect_state()
+            if state != "running":
+                raise RuntimeError(
+                    f"postgres container '{self._name}' is '{state}', not running -- it died "
+                    f"during startup rather than being slow. docker logs:\n{self._tail_logs()}"
+                )
             ready = subprocess.run(
                 ["docker", "exec", self._name, "pg_isready", "-U", self.USER],
                 capture_output=True,
@@ -159,7 +227,9 @@ class PostgresContainer:
                     last_err = e
             time.sleep(0.25)
         raise RuntimeError(
-            f"postgres container '{self._name}' did not become ready within 30s; last err: {last_err}"
+            f"postgres container '{self._name}' did not become ready within {timeout_s}s "
+            f"(state={self._inspect_state()}); last err: {last_err}. "
+            f"docker logs:\n{self._tail_logs()}"
         )