pbuffer 0.1.0__py3-none-any.whl

patternbuffer/refer.py

@@ -0,0 +1,256 @@
+"""refer(): reference resolution, the fourth boundary operation
+(whitepaper §9; spec §9.3). Three-tier cascade, cheapest first; tier 1
+is deterministic and makes no model call. Low confidence never guesses.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from patternbuffer.buffer import PatternBuffer
+from patternbuffer.identity import IdentityRegistry
+from patternbuffer.indexes import Indexes
+from patternbuffer.model import ATTR_PREFIX, CANON
+
+logger = logging.getLogger(__name__)
+
+RESOLVED = "resolved"
+CANDIDATES = "candidates"
+UNDERDETERMINED = "underdetermined"
+
+_TIER2_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "entity_id": {"type": ["string", "null"]},
+        "confidence": {"type": "number"},
+        "signals": {"type": "array", "items": {"type": "string"}},
+    },
+    # No required fields (HD 081): "no match" is a FIRST-CLASS outcome — a
+    # genuinely unresolvable reference (off-script/willy-nilly play) lets the
+    # model omit `entity_id` entirely rather than violate a required field and
+    # burn a re-ask. The consumer is fully `.get`-defended and treats a
+    # missing/null entity_id (or sub-floor confidence) as UNDERDETERMINED
+    # ("nothing here" — the host's ask), never an error.
+    "required": [],
+}
+_TIER2_FLOOR = 0.75
+
+# Leading determiners stripped before reference resolution (HD 003): a
+# possessive or article in front of a referring expression is surface
+# grammar, not identity ("my brass measuring spoon" is the spoon).
+_DETERMINERS = frozenset(
+    {"the", "a", "an", "my", "your", "his", "her", "its", "their", "our"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Resolution:
+    status: str
+    entity_id: str | None = None
+    candidates: tuple[str, ...] = ()
+    receipt: dict = field(default_factory=dict)  # tier, signals, confidence
+
+
+class Refer:
+    def __init__(
+        self,
+        buffer: PatternBuffer,
+        indexes: Indexes,
+        registry: IdentityRegistry,
+        model: Callable[[str, dict], Any] | None = None,
+        ingestor: "Any | None" = None,
+    ) -> None:
+        self._buffer = buffer
+        self._indexes = indexes
+        self._registry = registry
+        self._model = model
+        # Alias accrual (letter 018, mechanic 2) appends through the gate's
+        # role; without an ingestor wired, resolution still works but the
+        # world does not learn its users' words.
+        self._ingestor = ingestor
+
+    def _accrue_alias(self, description: str, entity_id: str, receipt: dict) -> None:
+        """Memoize a tier-2 resolution as an alias assertion carrying the
+        resolution receipt — each synonym costs one tier-2 call once, then
+        is tier-1a forever. A learned alias never outranks an exact name
+        (by_alias hits both; exact-name uniqueness still wins tier 1a, and
+        a later collision is ordinary ambiguity -> tier 2)."""
+        if self._ingestor is None:
+            return
+        rows = self._ingestor.ingest_structured([
+            {"entity": entity_id, "attribute": "alias",
+             "value": description.strip().lower(), "timeless": True,
+             "status": "inferred"},
+        ])
+        self._buffer.append(
+            entity=rows[0].id, attribute="source",
+            value=f"refer:tier2:{json.dumps(receipt.get('signals', []))[:80]}",
+            status="inferred", role=self._ingestor._role,
+        )
+        logger.info("alias accrued: %r -> %s", description, entity_id)
+
+    def __call__(
+        self,
+        description: str,
+        scope: str | list[str] | None = None,
+        frame: str = CANON,
+        constraints: list[tuple[str, str]] | None = None,
+        as_of: float | None = None,
+        asserted_as_of: int | None = None,
+    ) -> Resolution:
+        # ---- Tier 1a: exact name/alias hit through the identity registry.
+        # Try the raw expression and its determiner-stripped core (HD 003):
+        # "my brass measuring spoon" misses the exact name otherwise.
+        core = self._strip_determiner(description)
+        hits = self._registry.by_alias(description)
+        if core != description.strip().lower():
+            hits = hits | self._registry.by_alias(core)
+        if len(hits) == 1:
+            return Resolution(RESOLVED, next(iter(hits)),
+                              receipt={"tier": 1, "signals": ["alias_exact"]})
+
+        # ---- Tier 1b: constraint inversion — resolve the container by the
+        # contained, the owner by the possession. Flip the lookup before
+        # any linguistic judgment.
+        if constraints:
+            inverted = self._invert(constraints, frame, as_of, asserted_as_of)
+            if inverted is not None:
+                return inverted
+
+        # ---- Tier 1c: unique-kind-in-scope ("the drawer" where the scene
+        # holds exactly one drawer).
+        kind = self._kind_word(description)
+        if kind is not None:
+            members = self._scope_members(scope, frame, as_of, asserted_as_of)
+            of_kind = [
+                e for e in members
+                if self._entity_kind(e, frame, as_of, asserted_as_of) == kind
+            ]
+            if len(of_kind) == 1:
+                return Resolution(RESOLVED, of_kind[0],
+                                  receipt={"tier": 1, "signals": ["unique_kind_in_scope"]})
+            if len(of_kind) > 1:
+                return self._resolve_tier2(description, tuple(sorted(of_kind)))
+        if len(hits) > 1:
+            return self._resolve_tier2(description, tuple(sorted(hits)))
+
+        # ---- Zero-candidate escalation (letter 018, mechanic 1): a synonym
+        # yields zero tier-1 matches; with a scope provided, that is exactly
+        # tier 2's judgment — vocabulary miss must not masquerade as absence.
+        # Scope-bounded ONLY: never world-scope for this path.
+        if scope is not None:
+            members = self._scope_members(scope, frame, as_of, asserted_as_of)
+            if members:
+                return self._resolve_tier2(description, tuple(sorted(members)))
+
+        # Nothing deterministic and no candidates: underdetermined.
+        return Resolution(UNDERDETERMINED, receipt={"tier": 3, "signals": []})
+
+    # ------------------------------------------------------------- tier 1
+
+    def _invert(self, constraints, frame, as_of, asserted_as_of) -> Resolution | None:
+        for relation, anchor in constraints:
+            if relation == "contains":
+                chain = self._indexes.locate(anchor, frame, as_of, asserted_as_of)
+                if chain:
+                    return Resolution(
+                        RESOLVED, chain[0],
+                        receipt={"tier": 1, "signals": [f"constraint_inversion:contains({anchor})"]},
+                    )
+            elif relation == "owned_by" or relation == "held_by":
+                folded = self._indexes.fold_key(anchor, "in", frame, as_of, asserted_as_of)
+                if folded.winner is not None and folded.winner.value_type == "entity":
+                    return Resolution(
+                        RESOLVED, self._indexes.resolve_entity(folded.winner.value),
+                        receipt={"tier": 1, "signals": [f"constraint_inversion:{relation}({anchor})"]},
+                    )
+        return None
+
+    @staticmethod
+    def _strip_determiner(description: str) -> str:
+        """Lowercase and drop a single leading article/possessive token
+        (HD 003). A no-determiner phrase passes through unchanged."""
+        text = description.strip().lower()
+        head, _, rest = text.partition(" ")
+        if head in _DETERMINERS and rest:
+            return rest.strip()
+        return text
+
+    def _kind_word(self, description: str) -> str | None:
+        """A bare kind reference ("the drawer", "my spoon") → the kind
+        token. Accepts an optional leading article or possessive (HD 003);
+        broadening only adds matches, so "the X" still parses identically."""
+        det = "|".join(sorted(_DETERMINERS))
+        m = re.match(rf"^(?:{det})\s+([a-z][a-z_ ]*)$", description.strip().lower())
+        return m.group(1).replace(" ", "_") if m else None
+
+    def _scope_members(self, scope, frame, as_of, asserted_as_of) -> list[str]:
+        if scope is None:
+            # World scope: every entity with a kind row.
+            return sorted(
+                {
+                    self._indexes.resolve_entity(r.entity)
+                    for r in self._buffer.visible(
+                        attribute="kind", frame=frame,
+                        valid_as_of=as_of, asserted_as_of=asserted_as_of,
+                    )
+                    if not r.entity.startswith("a:")
+                    and not r.entity.startswith(ATTR_PREFIX)
+                }
+            )
+        roots = [scope] if isinstance(scope, str) else list(scope)
+        members: set[str] = set()
+        frontier = [self._indexes.resolve_entity(r) for r in roots]
+        seen: set[str] = set()
+        while frontier:
+            e = frontier.pop(0)
+            if e in seen:
+                continue
+            seen.add(e)
+            members.add(e)
+            frontier.extend(self._indexes.contents(e, frame, as_of, asserted_as_of))
+        return sorted(members)
+
+    def _entity_kind(self, entity, frame, as_of, asserted_as_of) -> str | None:
+        result = self._indexes.fold_key(entity, "kind", frame, as_of, asserted_as_of)
+        return result.winner.value if result.winner else None
+
+    # ------------------------------------------------------------- tier 2
+
+    def _resolve_tier2(self, description: str, candidates: tuple[str, ...]) -> Resolution:
+        """Strict-contract cheap call judging candidates; returns a
+        resolution receipt. Below the floor -> tier 3: never guess."""
+        if self._model is None:
+            return Resolution(CANDIDATES, candidates=candidates,
+                              receipt={"tier": 2, "signals": ["no_model"]})
+        prompt = (
+            f"A reference must resolve to exactly one entity or none.\n"
+            f"Reference: {description!r}\nCandidates: {list(candidates)}\n"
+            "Judge by name match, recency, possession, and discourse context. "
+            "If genuinely ambiguous, return entity_id=null with low confidence. "
+            "If NO candidate matches at all (the referenced thing does not exist "
+            "in this world), return entity_id=null — a genuine no-match is a "
+            "valid, expected outcome, never an error."
+        )
+        try:
+            out = self._model(prompt, _TIER2_SCHEMA)
+        except Exception:
+            logger.exception("refer tier-2 model call failed")
+            return Resolution(CANDIDATES, candidates=candidates,
+                              receipt={"tier": 2, "signals": ["model_error"]})
+        receipt = {
+            "tier": 2,
+            "candidates": list(candidates),
+            "signals": out.get("signals", []),
+            "confidence": out.get("confidence", 0.0),
+        }
+        if out.get("entity_id") in candidates and out.get("confidence", 0.0) >= _TIER2_FLOOR:
+            resolution = Resolution(RESOLVED, out["entity_id"], receipt=receipt)
+            self._accrue_alias(description, out["entity_id"], receipt)
+            return resolution
+        # Tier 3 contract: the ask is the host's to deliver.
+        return Resolution(UNDERDETERMINED, candidates=candidates, receipt=receipt)

patternbuffer/roles.py

@@ -0,0 +1,77 @@
+"""The role-authority matrix, enforced in code (whitepaper §12, spec §6).
+
+Every append to the buffer requires a ``WriterRole`` capability whose
+``allowed_statuses`` admits the row's provenance status. Capabilities
+cannot be minted by application code: the constructor demands a
+module-private token reachable only through the factory functions below,
+which are called from ``World`` wiring (and, for the builder role, from
+``dump.build`` alone).
+
+The classifier, projector, and renderer hold no capability at all —
+there is nothing they can call that writes the log.
+"""
+
+from __future__ import annotations
+
+from patternbuffer.model import STATUSES
+
+_TOKEN = object()
+
+
+class RoleViolation(PermissionError):
+    """An append was attempted outside the role-authority matrix."""
+
+
+class WriterRole:
+    """A write capability: a name plus the statuses it may append."""
+
+    __slots__ = ("name", "allowed_statuses")
+
+    def __init__(self, name: str, allowed_statuses: frozenset[str], *, _token: object = None) -> None:
+        if _token is not _TOKEN:
+            raise RoleViolation(
+                "WriterRole cannot be constructed by application code; "
+                "capabilities are minted only in World wiring"
+            )
+        bad = allowed_statuses - STATUSES
+        if bad:
+            raise ValueError(f"unknown statuses: {sorted(bad)}")
+        self.name = name
+        self.allowed_statuses = allowed_statuses
+
+    def check(self, status: str) -> None:
+        if status not in self.allowed_statuses:
+            raise RoleViolation(
+                f"role {self.name!r} may not append status {status!r} "
+                f"(allowed: {sorted(self.allowed_statuses)})"
+            )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"WriterRole({self.name!r})"
+
+
+def _make_engine_roles() -> dict[str, WriterRole]:
+    """Mint the engine's writer roles. Called only from World wiring.
+
+    Note what is absent: no role may append ``default`` — it exists only
+    in materialization payloads, never in the log (whitepaper §7).
+    """
+    return {
+        "ingestor": WriterRole(
+            "ingestor", frozenset({"stated", "observed", "inferred", "assumed"}), _token=_TOKEN
+        ),
+        "resolver": WriterRole("resolver", frozenset({"generated"}), _token=_TOKEN),
+        "truth_maintenance": WriterRole(
+            "truth_maintenance", frozenset({"retracted", "inferred"}), _token=_TOKEN
+        ),
+    }
+
+
+def _make_builder_role() -> WriterRole:
+    """Mint the dump-replay capability. Called only from ``dump.build``.
+
+    The builder may replay any logged status (the dump already carries
+    the log as it was) except ``default``, which never appears in a log
+    and therefore never in a dump.
+    """
+    return WriterRole("builder", STATUSES - {"default"}, _token=_TOKEN)

patternbuffer/salience.py

@@ -0,0 +1,170 @@
+"""Projection-time salience: a rebuildable ranking sidecar.
+
+Salience is derived from the assertion log and classifier sidecar. It is
+cached for retrieval speed, but never authored into the log.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+
+from patternbuffer.buffer import PatternBuffer
+from patternbuffer.classify import STATE, Classifier
+from patternbuffer.indexes import Indexes
+from patternbuffer.model import ATTR_PREFIX, CANON, Assertion
+
+SALIENCE_PARAMS = {
+    "weights": {
+        "recency": 0.40,
+        "reference_frequency": 0.25,
+        "reinforcement": 0.20,
+        "delta_from_baseline": 0.15,
+    },
+    "ref_scale": 8.0,
+    "reinf_scale": 8.0,
+}
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS sidecar_salience (
+  entity             TEXT NOT NULL,
+  frame              TEXT NOT NULL,
+  as_of_key          TEXT NOT NULL,
+  score              REAL NOT NULL,
+  head               INTEGER NOT NULL,
+  classifier_version INTEGER NOT NULL,
+  PRIMARY KEY (entity, frame, as_of_key)
+);
+"""
+
+
+class SalienceIndex:
+    """Derived, disposable salience scores over the current log."""
+
+    def __init__(
+        self,
+        buffer: PatternBuffer,
+        classifier: Classifier,
+        indexes: Indexes,
+    ) -> None:
+        self._buffer = buffer
+        self._classifier = classifier
+        self._indexes = indexes
+        self._ensure_schema()
+
+    def _ensure_schema(self) -> None:
+        self._buffer.raw_connection().executescript(_SCHEMA)
+        self._buffer.raw_connection().commit()
+
+    @staticmethod
+    def _as_of_key(as_of: float | None) -> str:
+        return json.dumps(as_of, sort_keys=True)
+
+    def rebuild(self) -> None:
+        """Drop cached scores; they will be recomputed on demand."""
+        self._ensure_schema()
+        self._buffer.raw_connection().execute("DELETE FROM sidecar_salience")
+        self._buffer.raw_connection().commit()
+
+    def salience(
+        self,
+        entity: str,
+        frame: str = CANON,
+        as_of: float | None = None,
+    ) -> float:
+        entity = self._indexes.resolve_entity(entity)
+        head = self._buffer.head()
+        version = self._classifier.version
+        as_of_key = self._as_of_key(as_of)
+        self._ensure_schema()
+        row = self._buffer.raw_connection().execute(
+            "SELECT score, head, classifier_version FROM sidecar_salience"
+            " WHERE entity = ? AND frame = ? AND as_of_key = ?",
+            (entity, frame, as_of_key),
+        ).fetchone()
+        if row is not None and int(row[1]) == head and int(row[2]) == version:
+            return float(row[0])
+        score = self._compute(entity, frame, as_of)
+        self._buffer.raw_connection().execute(
+            "INSERT OR REPLACE INTO sidecar_salience"
+            " (entity, frame, as_of_key, score, head, classifier_version)"
+            " VALUES (?, ?, ?, ?, ?, ?)",
+            (entity, frame, as_of_key, score, head, version),
+        )
+        self._buffer.raw_connection().commit()
+        return score
+
+    def _visible_entity_rows(
+        self, entity: str, frame: str, as_of: float | None
+    ) -> list[Assertion]:
+        closure = sorted(self._indexes._closure_of(entity))
+        if not closure:
+            return []
+        return [
+            row
+            for row in self._buffer.visible(
+                entity_in=closure, frame=frame, valid_as_of=as_of
+            )
+            if not row.entity.startswith(ATTR_PREFIX)
+        ]
+
+    def _compute(self, entity: str, frame: str, as_of: float | None) -> float:
+        rows = self._visible_entity_rows(entity, frame, as_of)
+        head = self._buffer.head()
+        max_asserted = max((r.asserted_at for r in rows), default=0)
+        recency = (max_asserted / head) if head else 0.0
+
+        incoming = self._indexes.incoming_refs(entity, frame, as_of)
+        ref_scale = SALIENCE_PARAMS["ref_scale"]
+        reference_frequency = min(1.0, math.log1p(len(incoming)) / math.log1p(ref_scale))
+
+        valid_times = {r.valid_from for r in rows}
+        reinf_scale = SALIENCE_PARAMS["reinf_scale"]
+        reinforcement = min(1.0, math.log1p(len(valid_times)) / math.log1p(reinf_scale))
+
+        delta = self._delta_from_baseline(entity, rows, frame, as_of)
+
+        weights = SALIENCE_PARAMS["weights"]
+        return (
+            weights["recency"] * recency
+            + weights["reference_frequency"] * reference_frequency
+            + weights["reinforcement"] * reinforcement
+            + weights["delta_from_baseline"] * delta
+        )
+
+    def _delta_from_baseline(
+        self,
+        entity: str,
+        rows: list[Assertion],
+        frame: str,
+        as_of: float | None,
+    ) -> float:
+        by_fold_attr: dict[str, list[Assertion]] = {}
+        for row in rows:
+            if (
+                row.entity.startswith("a:")
+                or row.value_type == "unresolved"
+                or self._classifier.durability(row.id) != STATE
+            ):
+                continue
+            by_fold_attr.setdefault(self._indexes.fold_attribute(row.attribute), []).append(row)
+        if not by_fold_attr:
+            return 0.0
+        current = self._indexes.current_state(entity, frame, as_of)
+
+        def recency_key(row: Assertion) -> tuple[float, int]:
+            return (
+                row.valid_from if row.valid_from is not None else float("-inf"),
+                row.asserted_at,
+            )
+
+        for attr, attr_rows in by_fold_attr.items():
+            result = current.get(attr)
+            if result is None or result.winner is None:
+                continue
+            if self._classifier.durability(result.winner.id) != STATE:
+                continue
+            baseline = min(attr_rows, key=recency_key)
+            if result.winner.id != baseline.id and recency_key(result.winner) > recency_key(baseline):
+                return 1.0
+        return 0.0

patternbuffer/semantics.py

@@ -0,0 +1,192 @@
+"""Attribute semantics as data (ATTRIBUTE-SEMANTICS-V1).
+
+Attribute-level *behavior* — arity (functional vs set-valued), relation
+family (containment tree / lateral graph / none), fold policy (last-write
+vs move-supersession), and structural-ness — lifted out of the engine's
+code constants into per-world, rebuildable, *declared* semantics that every
+consumer reads through this one service. Domain vocabulary carries its own
+fold behavior without engine edits.
+
+Declarations are ordinary assertions about an ``attr:<name>`` entity (the
+canonicalization-as-receipts pattern generalized); the sidecar here is a
+rebuildable view over them, never truth (P2). Unspecified attributes return
+the built-in defaults, so a world with zero declarations behaves exactly as
+the pre-RFC engine did.
+
+Two invariants this module owns (whitepaper guardrail; spec §5):
+- **Inviolable core.** The engine's constitutional predicates (the
+  containment family, ``kind``/``connects_to``/``adjacent_to``/``caused_by``,
+  the identity predicates) can never be redeclared. A host adds domain
+  semantics; it never redefines a primitive.
+- **Declared semantics never reject a fact.** They govern how a row *folds*,
+  never whether it is *admitted* (the Kernos rejection-test). The only
+  rejection is authority-on-vocabulary (a forbidden ``attr:*`` write), never
+  schema-on-world-facts.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from patternbuffer.buffer import PatternBuffer
+from patternbuffer.model import (
+    ATTR_PREFIX,
+    CONTAINMENT_FAMILY,
+    INVIOLABLE_CORE,
+    SEMANTICS_PREDICATES,
+    SET_VALUED_ATTRIBUTES,
+    STRUCTURAL_PREDICATES,
+)
+
+logger = logging.getLogger(__name__)
+
+# Axis values (fixed enums).
+FUNCTIONAL, SET_VALUED = "functional", "set_valued"
+CONTAINMENT, LATERAL, NONE = "containment", "lateral", "none"
+LAST_WRITE, MOVE, ACCRUE = "last_write", "move", "accrue"
+
+ARITIES = frozenset({FUNCTIONAL, SET_VALUED})
+RELATION_FAMILIES = frozenset({CONTAINMENT, LATERAL, NONE})
+FOLD_POLICIES = frozenset({LAST_WRITE, MOVE, ACCRUE})
+
+# Built-in lateral graph attributes; everything set-valued that is not a graph
+# edge is plain set data.
+_LATERAL = frozenset({"connects_to", "adjacent_to"})
+
+# Names with non-default built-in semantics. Family helpers below derive their
+# seed sets through builtin_default() so behavioral constants are read in one
+# place.
+_BUILTIN_DEFAULT_ATTRIBUTES = frozenset(
+    {
+        "in",
+        "within",
+        "held_by",
+        "worn_by",
+        "carried_by",
+        "name",
+        "alias",
+        "connects_to",
+        "adjacent_to",
+        "maybe_same_as",
+        "same_as",
+        "kind",
+        "caused_by",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Semantics:
+    """The four orthogonal attribute-level axes."""
+
+    arity: str
+    relation_family: str
+    fold_policy: str
+    structural: bool
+
+
+def builtin_default(attribute: str) -> Semantics:
+    """Today's behavior, as data — the default for any undeclared attribute."""
+    arity = SET_VALUED if attribute in SET_VALUED_ATTRIBUTES else FUNCTIONAL
+    if attribute in CONTAINMENT_FAMILY:
+        family, policy = CONTAINMENT, MOVE
+    elif attribute in _LATERAL:
+        family, policy = LATERAL, LAST_WRITE
+    else:
+        family, policy = NONE, LAST_WRITE
+    return Semantics(arity, family, policy, attribute in STRUCTURAL_PREDICATES)
+
+
+class AttributeSemantics:
+    """Per-world, rebuildable attribute-semantics view. Holds no truth (P2):
+    the declarations live in the log as ``attr:*`` rows; this is their fold."""
+
+    def __init__(self, buffer: PatternBuffer) -> None:
+        self._buffer = buffer
+        self._declared: dict[str, dict[str, object]] = {}
+        self._rebuilt_at = -1
+        self.rebuild()
+
+    def rebuild(self) -> None:
+        """Scan visible ``attr:*`` declarations into the sidecar (parity with
+        the canonicalization map and the durability sidecar)."""
+        declared: dict[str, dict[str, object]] = {}
+        for row in self._buffer.visible(entity_prefix=ATTR_PREFIX):
+            if row.attribute in SEMANTICS_PREDICATES:
+                name = row.entity[len(ATTR_PREFIX):]
+                declared.setdefault(name, {})[row.attribute] = row.value
+        self._declared = declared
+        self._rebuilt_at = self._buffer.head()
+
+    def _refresh(self) -> None:
+        if self._buffer.head() != self._rebuilt_at:
+            self.rebuild()
+
+    # ----------------------------------------------------------------- read
+
+    def semantics(self, attribute: str) -> Semantics:
+        """Declared semantics over the built-in default for one attribute."""
+        self._refresh()
+        base = builtin_default(attribute)
+        d = self._declared.get(attribute)
+        if not d:
+            return base
+        return Semantics(
+            arity=str(d.get("arity", base.arity)),
+            relation_family=str(d.get("relation_family", base.relation_family)),
+            fold_policy=str(d.get("fold_policy", base.fold_policy)),
+            structural=bool(d.get("structural", base.structural)),
+        )
+
+    def is_set_valued(self, attribute: str) -> bool:
+        return self.semantics(attribute).arity == SET_VALUED
+
+    def is_containment(self, attribute: str) -> bool:
+        return self.semantics(attribute).relation_family == CONTAINMENT
+
+    def is_lateral(self, attribute: str) -> bool:
+        return self.semantics(attribute).relation_family == LATERAL
+
+    def is_accrue(self, attribute: str) -> bool:
+        return self.semantics(attribute).fold_policy == ACCRUE
+
+    def is_structural(self, attribute: str) -> bool:
+        return self.semantics(attribute).structural
+
+    def is_declared(self, attribute: str) -> bool:
+        """Whether an explicit ``attr:*`` declaration exists (vs. defaulting)."""
+        self._refresh()
+        return attribute in self._declared
+
+    def containment_family(self) -> set[str]:
+        """All attributes that fold as the single containment key — the
+        built-in family plus any declared ``relation_family=containment``."""
+        self._refresh()
+        out = {
+            name for name in _BUILTIN_DEFAULT_ATTRIBUTES
+            if builtin_default(name).relation_family == CONTAINMENT
+        }
+        for name in self._declared:
+            if self.semantics(name).relation_family == CONTAINMENT:
+                out.add(name)
+        return out
+
+    def lateral_family(self) -> set[str]:
+        """All attributes that form the lateral graph (``path``)."""
+        self._refresh()
+        out = {
+            name for name in _BUILTIN_DEFAULT_ATTRIBUTES
+            if builtin_default(name).relation_family == LATERAL
+        }
+        for name in self._declared:
+            if self.semantics(name).relation_family == LATERAL:
+                out.add(name)
+        return out
+
+    # ------------------------------------------------------------- authority
+
+    @staticmethod
+    def is_core(attribute: str) -> bool:
+        """A constitutional predicate that can never be redeclared (spec §5)."""
+        return attribute in INVIOLABLE_CORE