chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/engine/targets.py

@@ -0,0 +1,342 @@
+"""Named targets: a pack-provided set of graph selectors, e.g. `rtl:<block>` (M2-11a).
+
+A target is what a person asks for in one word, `chipgraph build rtl:timer`, instead of
+naming every rule. A pack ships its targets as YAML files in its `targets/` directory,
+one per file::
+
+    schema_version: 1
+    target: rtl                     # the name: `rtl:<params>`
+    description: The RTL of one block, from its plan to a pull request.
+    params:
+      - { name: block, description: A block of the profile. }
+    select:                         # graph selectors, `{param}` filled in
+      - select: "pack/plan_expand[block={block}]"
+      - select: "pack/pr_gate[block={block}]"
+        optional: true              # may match nothing (yet)
+
+`BuildGraph.select("rtl:timer")` (with a `TargetRegistry`) is the union of what each
+selector selects, each with its upstream instances, exactly as `select` of a rule id.
+A required selector that matches nothing is an error (an unknown param value, a pack
+that is off); an optional one is skipped. A selector is a rule selector only
+(`pack/name[k=v]`), never another target.
+
+Params are given in order after the colon, `rtl:timer`, or by name, `rtl:block=timer`,
+comma-separated. This module knows no pack, rule or project: only names and templates.
+
+A target file is data a pack ships, so it is read strictly: every selector is parsed when
+the file loads (a malformed one is an error then, not a selector skipped forever), its
+rule part is a literal rule id (no `:`, so never a target), `optional` is a real boolean,
+param names are unique, a YAML key given twice is an error, and the file's size, nesting
+depth and YAML aliases are capped. Errors are short and never quote the file's values.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Hashable, Iterable, Mapping
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StrictBool,
+    ValidationError,
+    field_validator,
+    model_validator,
+)
+
+from chipgraph.core.plugin_api.pack import Pack
+
+TARGETS_DIR = "targets"
+"""The directory of a pack that holds its target files."""
+MAX_FILE_BYTES = 64 * 1024
+"""The largest target file read."""
+MAX_YAML_DEPTH = 32
+"""The deepest nesting of YAML collections in a target file."""
+MAX_YAML_ALIASES = 16
+"""The most YAML aliases (`*name`) in a target file."""
+
+_NAME_RE = r"^[a-z][a-z0-9_-]*$"
+_VALUE_RE = re.compile(r"^[^\s\[\],=:]+$")
+_PLACEHOLDER_RE = re.compile(r"\{([^{}]+)\}")
+_RULE_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*/[a-z0-9][a-z0-9_]*$")
+"""A rule id, as the contracts' `RuleId` (a selector's rule part)."""
+_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_SELECTOR_VALUE_RE = re.compile(r"^[^\s\[\],=]+$")
+_MAX_ERRORS = 5
+_MAX_MSG = 200
+
+
+class TargetError(ValueError):
+    """A target file is invalid, or a target is unknown or given the wrong params."""
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class TargetParam(_Model):
+    """One param of a target."""
+
+    name: str = Field(pattern=r"^[a-z][a-z0-9_]*$", description="The param name.")
+    description: str = Field(default="", description="What the param is.")
+
+
+def check_selector(value: str) -> None:
+    """Raise `ValueError` unless `value` is a rule selector, `pack/name` or
+    `pack/name[k=v,...]` (values may hold `{param}` placeholders)."""
+    rule, bracket, rest = value.partition("[")
+    if not _RULE_ID_RE.match(rule):
+        raise ValueError(
+            "a target selector names a rule ('pack/name[...]', never a target), "
+            f"got {value[:_MAX_MSG]!r}"
+        )
+    if not bracket:
+        return
+    if not rest.endswith("]") or "[" in rest[:-1] or "]" in rest[:-1] or not rest[:-1]:
+        raise ValueError(f"malformed selector {value[:_MAX_MSG]!r}: expected '[key=value,...]'")
+    keys: set[str] = set()
+    for pair in rest[:-1].split(","):
+        key, sep, item = (p.strip() for p in pair.partition("="))
+        filled = _PLACEHOLDER_RE.sub("x", item)
+        if not sep or not _KEY_RE.match(key) or not _SELECTOR_VALUE_RE.match(filled):
+            raise ValueError(f"malformed selector {value[:_MAX_MSG]!r}: expected 'key=value'")
+        if "{" in filled or "}" in filled:
+            raise ValueError(f"malformed selector {value[:_MAX_MSG]!r}: a stray brace")
+        if key in keys:
+            raise ValueError(f"malformed selector {value[:_MAX_MSG]!r}: {key!r} given twice")
+        keys.add(key)
+
+
+class TargetSelector(_Model):
+    """One graph selector of a target."""
+
+    select: str = Field(description="A rule selector, `pack/name[k={param}]`.")
+    optional: StrictBool = Field(
+        default=False, description="It may match no instance (it is skipped then)."
+    )
+
+    @field_validator("select")
+    @classmethod
+    def _rule_selector(cls, value: str) -> str:
+        check_selector(value)
+        return value
+
+
+class TargetSpec(_Model):
+    """A named target: its params and selectors."""
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this file.")
+    name: str = Field(alias="target", pattern=_NAME_RE, description="The target's name.")
+    description: str = Field(default="", description="What building the target does.")
+    params: tuple[TargetParam, ...] = Field(default=(), description="The params, in order.")
+    select: tuple[TargetSelector, ...] = Field(min_length=1, description="The selectors.")
+    pack: str | None = Field(default=None, description="The pack that provides it.")
+
+    model_config = ConfigDict(extra="forbid", frozen=True, populate_by_name=True)
+
+    @model_validator(mode="after")
+    def _unique_params(self) -> TargetSpec:
+        names = [p.name for p in self.params]
+        twice = sorted({n for n in names if names.count(n) > 1})
+        if twice:
+            raise ValueError(f"param(s) {', '.join(twice)} declared twice")
+        return self
+
+    def selectors(self, params: Mapping[str, str]) -> tuple[TargetSelector, ...]:
+        """The selectors with `params` filled in."""
+        return tuple(
+            item.model_copy(update={"select": _fill(item.select, params, self.name)})
+            for item in self.select
+        )
+
+
+def _fill(template: str, params: Mapping[str, str], name: str) -> str:
+    def _replace(match: re.Match[str]) -> str:
+        key = match.group(1)
+        if key not in params:
+            raise TargetError(f"target {name!r}: selector {template!r} uses unknown {{{key}}}")
+        return params[key]
+
+    return _PLACEHOLDER_RE.sub(_replace, template)
+
+
+class TargetRegistry:
+    """The targets of a project's packs, by name."""
+
+    def __init__(self, specs: Iterable[TargetSpec] = ()) -> None:
+        self._specs: dict[str, TargetSpec] = {}
+        for spec in specs:
+            self.add(spec)
+
+    def add(self, spec: TargetSpec) -> None:
+        """Register `spec`; a second target of the same name is an error."""
+        other = self._specs.get(spec.name)
+        if other is not None:
+            raise TargetError(
+                f"target {spec.name!r} is defined twice (packs {other.pack!r} and {spec.pack!r})"
+            )
+        for item in spec.select:
+            for key in _PLACEHOLDER_RE.findall(item.select):
+                if key not in {p.name for p in spec.params}:
+                    raise TargetError(
+                        f"target {spec.name!r}: selector {item.select!r} uses {{{key}}}, "
+                        "which is not one of its params"
+                    )
+        self._specs[spec.name] = spec
+
+    def names(self) -> tuple[str, ...]:
+        """Every target name, sorted."""
+        return tuple(sorted(self._specs))
+
+    def get(self, name: str) -> TargetSpec | None:
+        """The target called `name`, if any."""
+        return self._specs.get(name)
+
+    def is_target(self, text: str) -> bool:
+        """Whether `text` names a target: `<name>` or `<name>:<params>` of a known name."""
+        name = text.partition(":")[0]
+        return "/" not in name and "[" not in name and name in self._specs
+
+    def parse(self, text: str) -> tuple[TargetSpec, dict[str, str]]:
+        """The target `text` names and its params. Raises `TargetError`."""
+        name, _, rest = text.partition(":")
+        spec = self._specs.get(name)
+        if spec is None:
+            known = ", ".join(self.names()) or "none"
+            raise TargetError(f"unknown target {name!r}; known targets: {known}")
+        wanted = [p.name for p in spec.params]
+        values: dict[str, str] = {}
+        parts = [p.strip() for p in rest.split(",")] if rest else []
+        for index, part in enumerate(parts):
+            key, sep, value = part.partition("=")
+            if not sep:
+                if index >= len(wanted):
+                    raise TargetError(f"target {name!r} takes {len(wanted)} param(s): {text!r}")
+                key, value = wanted[index], part
+            key, value = key.strip(), value.strip()
+            if key not in wanted:
+                raise TargetError(f"target {name!r} has no param {key!r} (params: {wanted})")
+            if key in values:
+                raise TargetError(f"target {name!r}: param {key!r} given twice in {text!r}")
+            if not _VALUE_RE.match(value):
+                raise TargetError(f"target {name!r}: invalid value {value!r} for {key!r}")
+            values[key] = value
+        missing = [k for k in wanted if k not in values]
+        if missing:
+            usage = f"{name}:" + ",".join(f"<{k}>" for k in wanted)
+            raise TargetError(f"target {name!r} needs {', '.join(missing)}: write {usage!r}")
+        return spec, values
+
+    def resolve(self, text: str) -> tuple[TargetSelector, ...]:
+        """The selectors of the target `text`, params filled in. Raises `TargetError`."""
+        spec, values = self.parse(text)
+        return spec.selectors(values)
+
+    def describe_params(self, text: str) -> str:
+        """`k='v', ...` of the target `text`'s params, for an error message."""
+        try:
+            _, values = self.parse(text)
+        except TargetError:
+            return text
+        return ", ".join(f"{k}={v!r}" for k, v in values.items())
+
+
+class _StrictLoader(yaml.SafeLoader):
+    """`yaml.SafeLoader` that refuses duplicate keys, deep nesting and many aliases."""
+
+    def __init__(self, stream: str) -> None:
+        super().__init__(stream)
+        self._depth = 0
+        self._aliases = 0
+
+    def compose_node(self, parent: yaml.Node | None, index: object) -> yaml.Node | None:
+        if self.check_event(yaml.AliasEvent):
+            self._aliases += 1
+            if self._aliases > MAX_YAML_ALIASES:
+                raise yaml.YAMLError(f"more than {MAX_YAML_ALIASES} YAML aliases")
+        self._depth += 1
+        try:
+            if self._depth > MAX_YAML_DEPTH:
+                raise yaml.YAMLError(f"YAML nested deeper than {MAX_YAML_DEPTH} levels")
+            return super().compose_node(parent, index)  # type: ignore[arg-type]
+        finally:
+            self._depth -= 1
+
+    def construct_mapping(
+        self, node: yaml.MappingNode, deep: bool = False
+    ) -> dict[Hashable, object]:
+        seen: set[object] = set()
+        for key_node, _ in node.value:
+            key = self.construct_object(key_node, deep=True)
+            try:
+                twice = key in seen
+            except TypeError:
+                continue  # an unhashable key: SafeConstructor refuses it below
+            if twice:
+                mark = key_node.start_mark
+                raise yaml.YAMLError(f"line {mark.line + 1}: a key is given twice")
+            seen.add(key)
+        return super().construct_mapping(node, deep=deep)
+
+
+def _short(exc: ValidationError) -> str:
+    """The validation errors as `where: what`, without the values (they may be huge)."""
+    errors = exc.errors(include_url=False, include_input=False, include_context=False)
+    parts = [
+        f"{'.'.join(str(p) for p in e['loc']) or '<root>'}: {e['msg'][:_MAX_MSG]}"
+        for e in errors[:_MAX_ERRORS]
+    ]
+    if len(errors) > _MAX_ERRORS:
+        parts.append(f"and {len(errors) - _MAX_ERRORS} more")
+    return "; ".join(parts)
+
+
+def load_target_file(path: Path, *, pack: str | None = None) -> TargetSpec:
+    """Load one target file. Raises `TargetError` naming `path` (see the module)."""
+    try:
+        data = path.read_bytes()
+        if len(data) > MAX_FILE_BYTES:
+            raise TargetError(f"target file {path} is larger than {MAX_FILE_BYTES} bytes")
+        raw = yaml.load(data.decode("utf-8"), Loader=_StrictLoader)
+    except TargetError:
+        raise
+    except UnicodeDecodeError as exc:
+        raise TargetError(f"cannot read target file {path}: not UTF-8 (byte {exc.start})") from exc
+    except (OSError, yaml.YAMLError, RecursionError) as exc:
+        reason = str(exc)[:_MAX_MSG] if not isinstance(exc, RecursionError) else "nested too deep"
+        raise TargetError(f"cannot read target file {path}: {reason}") from exc
+    if not isinstance(raw, dict):
+        raise TargetError(f"target file {path} must contain a YAML mapping")
+    try:
+        spec = TargetSpec.model_validate({**raw, "pack": pack})
+    except ValidationError as exc:
+        raise TargetError(f"invalid target file {path}: {_short(exc)}") from exc
+    except RecursionError as exc:
+        raise TargetError(f"invalid target file {path}: nested too deep") from exc
+    return spec
+
+
+def load_pack_targets(pack: Pack) -> list[TargetSpec]:
+    """Every target in `<pack>/targets/*.yml` (none when the directory is absent)."""
+    directory = pack.root / TARGETS_DIR
+    if not directory.is_dir():
+        return []
+    files = sorted({*directory.glob("*.yml"), *directory.glob("*.yaml")})
+    return [load_target_file(path, pack=pack.manifest.name) for path in files]
+
+
+__all__ = [
+    "TARGETS_DIR",
+    "TargetError",
+    "TargetParam",
+    "TargetRegistry",
+    "TargetSelector",
+    "TargetSpec",
+    "check_selector",
+    "load_pack_targets",
+    "load_target_file",
+]

chipgraph/core/model/__init__.py

@@ -0,0 +1,98 @@
+"""The Design Model (DESIGN.md 4): a typed knowledge model of a chip design.
+
+`chipgraph.core.model` is the schema and SQLite-backed store (M1-01). It knows nothing
+about any specific chip project, bus or tool: entity kinds like `port` and `register`
+are generic hardware concepts. The query API (`model.block(...)`, `model.find(...)`,
+`model.trace(...)`) is built on top of this in M1-02.
+"""
+
+from chipgraph.core.model.entities import (
+    CORE_ENTITY_CLASSES,
+    BlockEntity,
+    ClockEntity,
+    DecisionEntity,
+    EarsParts,
+    EntityBase,
+    ExtEntity,
+    FieldEntity,
+    InterfaceEntity,
+    InterruptEntity,
+    MemoryRegionEntity,
+    ModuleEntity,
+    OpenItemEntity,
+    ParameterEntity,
+    PortEntity,
+    ProjectEntity,
+    RegisterEntity,
+    RequirementEntity,
+    ResetEntity,
+    TestEntity,
+)
+from chipgraph.core.model.json_value import JSONValue
+from chipgraph.core.model.keys import InvalidKeyError, key_kind, make_key, parse_key
+from chipgraph.core.model.model import DesignModel, ModelConflict
+from chipgraph.core.model.provenance import Provenance
+from chipgraph.core.model.query import (
+    BlockInfo,
+    EntityMatch,
+    ImpactNode,
+    ImpactResult,
+    ModelQuery,
+    NeighborResult,
+    QueryError,
+    SearchResult,
+    TraceResult,
+)
+from chipgraph.core.model.registry import DEFAULT_ENTITY_KINDS, DuplicateKindError, EntityKinds
+from chipgraph.core.model.relations import CORE_RELATION_KINDS, CoreRelationKind, Relation
+from chipgraph.core.model.store import ModelStore, ModelStoreError, SearchHit, default_model_db_path
+
+__all__ = [
+    "CORE_ENTITY_CLASSES",
+    "CORE_RELATION_KINDS",
+    "DEFAULT_ENTITY_KINDS",
+    "BlockEntity",
+    "BlockInfo",
+    "ClockEntity",
+    "CoreRelationKind",
+    "DecisionEntity",
+    "DesignModel",
+    "DuplicateKindError",
+    "EarsParts",
+    "EntityBase",
+    "EntityKinds",
+    "EntityMatch",
+    "ExtEntity",
+    "FieldEntity",
+    "ImpactNode",
+    "ImpactResult",
+    "InterfaceEntity",
+    "InterruptEntity",
+    "InvalidKeyError",
+    "JSONValue",
+    "MemoryRegionEntity",
+    "ModelConflict",
+    "ModelQuery",
+    "ModelStore",
+    "ModelStoreError",
+    "ModuleEntity",
+    "NeighborResult",
+    "OpenItemEntity",
+    "ParameterEntity",
+    "PortEntity",
+    "ProjectEntity",
+    "Provenance",
+    "QueryError",
+    "RegisterEntity",
+    "Relation",
+    "RequirementEntity",
+    "ResetEntity",
+    "SearchHit",
+    "SearchResult",
+    "TestEntity",
+    "TraceResult",
+    "default_model_db_path",
+    "key_kind",
+    "make_key",
+    "parse_key",
+]

chipgraph/core/model/entities.py

@@ -0,0 +1,244 @@
+"""The core Design Model entities (DESIGN.md 4.2).
+
+One frozen pydantic class per core kind, all sharing `EntityBase`. Every field beyond
+the base is optional: extractors fill in what they know, and later tasks (M1-04..M1-07)
+narrow things down over time. Anything an extractor cannot type yet goes in `attrs`.
+
+Entity kinds are generic hardware concepts (port, register, clock, ...). Nothing here
+names a specific chip project, bus protocol or tool.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from chipgraph.core.model.json_value import JSONValue
+from chipgraph.core.model.provenance import Provenance
+
+
+class EntityBase(BaseModel):
+    """Fields shared by every entity kind, core or pack-defined."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    kind: str = Field(description="The entity kind; overridden per subclass with a Literal.")
+    key: str = Field(description="The stable model key, e.g. 'register:timer.CTRL'.")
+    name: str = Field(description="A short human-readable name for this entity.")
+    source: Provenance = Field(
+        default_factory=Provenance, description="Where this fact was learned from."
+    )
+    attrs: dict[str, JSONValue] = Field(
+        default_factory=dict, description="Open-ended extra facts not covered by typed fields."
+    )
+
+
+class EarsParts(BaseModel):
+    """A requirement's text, broken into EARS-style structured parts (DESIGN.md 8/M3-08).
+
+    Optional: an extractor that only has the raw sentence leaves these unset.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    trigger: str | None = Field(default=None, description="The triggering event ('when ...').")
+    condition: str | None = Field(default=None, description="A qualifying state ('while ...').")
+    subject: str | None = Field(default=None, description="The system or object the REQ is about.")
+    action: str | None = Field(default=None, description="The required behavior ('shall ...').")
+
+
+class ProjectEntity(EntityBase):
+    """The top-level project or chip this Design Model describes."""
+
+    kind: Literal["project"] = "project"
+
+
+class BlockEntity(EntityBase):
+    """A design block (an IP or subsystem), e.g. 'timer'."""
+
+    kind: Literal["block"] = "block"
+    owner: str | None = Field(default=None, description="Who owns this block.")
+    path: str | None = Field(default=None, description="Repo-relative directory for this block.")
+
+
+class ModuleEntity(EntityBase):
+    """A single RTL module."""
+
+    kind: Literal["module"] = "module"
+    file: str | None = Field(default=None, description="Repo-relative file this module is in.")
+    block: str | None = Field(default=None, description="The model key of the owning block.")
+
+
+class PortEntity(EntityBase):
+    """A port on a module."""
+
+    kind: Literal["port"] = "port"
+    direction: Literal["input", "output", "inout"] | None = Field(
+        default=None, description="Port direction."
+    )
+    width: int | str | None = Field(
+        default=None, description="Port width: an int, or an unresolved expression string."
+    )
+    clock: str | None = Field(default=None, description="Model key of the clock this port is in.")
+    reset: str | None = Field(default=None, description="Model key of the reset this port uses.")
+    module: str | None = Field(default=None, description="Model key of the owning module.")
+
+
+class InterfaceEntity(EntityBase):
+    """A bus/protocol interface (APB, AXI, TileLink, ...), described as data."""
+
+    kind: Literal["interface"] = "interface"
+    protocol: str | None = Field(default=None, description="The protocol this interface follows.")
+
+
+class ClockEntity(EntityBase):
+    """A clock domain."""
+
+    kind: Literal["clock"] = "clock"
+    frequency_hz: float | None = Field(default=None, ge=0, description="Nominal frequency, in Hz.")
+
+
+class ResetEntity(EntityBase):
+    """A reset signal."""
+
+    kind: Literal["reset"] = "reset"
+    active_low: bool | None = Field(default=None, description="Whether this reset is active-low.")
+    sync: bool | None = Field(default=None, description="Whether this reset is synchronous.")
+
+
+class ParameterEntity(EntityBase):
+    """A module parameter."""
+
+    kind: Literal["parameter"] = "parameter"
+    value: str | int | float | bool | None = Field(
+        default=None, description="The parameter's value or default value."
+    )
+    module: str | None = Field(default=None, description="Model key of the owning module.")
+
+
+class RegisterEntity(EntityBase):
+    """A register."""
+
+    kind: Literal["register"] = "register"
+    block: str | None = Field(default=None, description="Model key of the owning block.")
+    offset: int | str | None = Field(
+        default=None, description="Byte offset: an int, or an unresolved expression string."
+    )
+    width: int | None = Field(default=None, ge=1, description="Register width, in bits.")
+    reset_value: int | str | None = Field(default=None, description="Reset value.")
+    access: str | None = Field(default=None, description="Access mode, e.g. 'rw', 'ro', 'w1c'.")
+
+
+# `register` shadows `ABCMeta.register` (pydantic model classes are ABCs), and pydantic
+# warns about it on every import. The field is an instance attribute and nothing calls
+# `FieldEntity.register(...)` as an ABC, so the name is kept (it is in the stored model and
+# its JSON Schema) and only that one warning is silenced.
+with warnings.catch_warnings():
+    warnings.filterwarnings(
+        "ignore",
+        message='Field name "register" in "FieldEntity" shadows an attribute',
+        category=UserWarning,
+    )
+
+    class FieldEntity(EntityBase):
+        """A bit field within a register."""
+
+        kind: Literal["field"] = "field"
+        register: str | None = Field(default=None, description="Model key of the owning register.")
+        lsb: int | None = Field(default=None, ge=0, description="Least-significant bit index.")
+        msb: int | None = Field(default=None, ge=0, description="Most-significant bit index.")
+        access: str | None = Field(default=None, description="Access mode, e.g. 'rw', 'ro', 'w1c'.")
+        reset_value: int | str | None = Field(default=None, description="Reset value.")
+
+
+class InterruptEntity(EntityBase):
+    """An interrupt line."""
+
+    kind: Literal["interrupt"] = "interrupt"
+    block: str | None = Field(default=None, description="Model key of the owning block.")
+    line: int | None = Field(default=None, ge=0, description="Interrupt line number.")
+
+
+class MemoryRegionEntity(EntityBase):
+    """A region of the address map."""
+
+    kind: Literal["memory_region"] = "memory_region"
+    base: int | str | None = Field(
+        default=None, description="Base address: an int, or an unresolved expression string."
+    )
+    size: int | str | None = Field(
+        default=None, description="Region size in bytes: an int, or an unresolved expression."
+    )
+    block: str | None = Field(default=None, description="Model key of the owning block.")
+
+
+class RequirementEntity(EntityBase):
+    """A single requirement, usually with a REQ-ID."""
+
+    kind: Literal["requirement"] = "requirement"
+    text: str | None = Field(default=None, description="The requirement's full sentence.")
+    ears: EarsParts | None = Field(
+        default=None, description="Structured EARS parts, when available."
+    )
+
+
+class DecisionEntity(EntityBase):
+    """A recorded design decision (not to be confused with `contracts.Decision`)."""
+
+    kind: Literal["decision"] = "decision"
+    text: str | None = Field(default=None, description="What was decided.")
+    rationale: str | None = Field(default=None, description="Why it was decided.")
+
+
+class OpenItemEntity(EntityBase):
+    """An open question or todo against a spec."""
+
+    kind: Literal["open_item"] = "open_item"
+    status: Literal["open", "resolved"] | None = Field(
+        default=None, description="Whether this open item is still open."
+    )
+
+
+class TestEntity(EntityBase):
+    """A test, mapped back to the requirements it verifies."""
+
+    __test__ = False  # tell pytest this "Test*" class is not a test case to collect
+
+    kind: Literal["test"] = "test"
+    requirement_keys: tuple[str, ...] = Field(
+        default=(), description="Model keys of the requirements this test verifies."
+    )
+
+
+CORE_ENTITY_CLASSES: tuple[type[EntityBase], ...] = (
+    ProjectEntity,
+    BlockEntity,
+    ModuleEntity,
+    PortEntity,
+    InterfaceEntity,
+    ClockEntity,
+    ResetEntity,
+    ParameterEntity,
+    RegisterEntity,
+    FieldEntity,
+    InterruptEntity,
+    MemoryRegionEntity,
+    RequirementEntity,
+    DecisionEntity,
+    OpenItemEntity,
+    TestEntity,
+)
+"""Every core entity class, in the order they should appear in generated schemas."""
+
+
+class ExtEntity(EntityBase):
+    """A pack-defined entity kind the reader has no typed class registered for.
+
+    Round-trips losslessly: `kind` and every extra fact live in `attrs`/`kind` so a
+    store can persist and reload entities from packs it does not know about.
+    """
+
+    kind: str = Field(description="The pack-defined kind, e.g. 'pin_spec'.")