chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/contracts/event.py

@@ -0,0 +1,70 @@
+"""Events: the append-only record of what happened during a run."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Self
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, model_validator
+
+from chipgraph.core.contracts.types import FailureLabel, Sha256
+
+EventType = Literal[
+    "run_start",
+    "rule_start",
+    "tool_call",
+    "check_result",
+    "agent_turn",
+    "gate_wait",
+    "gate_decision",
+    "rule_done",
+    "rule_fail",
+    "run_stop",
+]
+"""The kind of thing that happened, recorded as one event in a run's journal."""
+
+
+class Event(BaseModel):
+    """A single entry in a run's append-only journal."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    run_id: str = Field(description="The id of the run this event belongs to.")
+    seq: int = Field(ge=0, description="The 0-based sequence number of this event within the run.")
+    ts: AwareDatetime = Field(description="When this event occurred.")
+    type: EventType = Field(description="The kind of event this is.")
+    rule_instance: str | None = Field(
+        default=None, description="The rule instance this event concerns, if any."
+    )
+    payload: dict[str, Any] = Field(default={}, description="Event-type-specific data.")
+    failure_label: FailureLabel | None = Field(
+        default=None, description="Why a rule failed; only set when type is 'rule_fail'."
+    )
+
+    @model_validator(mode="after")
+    def _check_failure_label_only_on_rule_fail(self) -> Self:
+        if self.failure_label is not None and self.type != "rule_fail":
+            raise ValueError("failure_label is only allowed when type='rule_fail'")
+        return self
+
+
+class RunManifest(BaseModel):
+    """A snapshot of everything needed to reproduce or audit a run."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    run_id: str = Field(description="The id of this run.")
+    started_at: AwareDatetime = Field(description="When this run started.")
+    target: str = Field(description="The build target this run was invoked with.")
+    chipgraph_version: str = Field(description="The chipgraph version that executed this run.")
+    profile_hash: Sha256 = Field(description="Hash of the resolved profile used for this run.")
+    profile_sources: tuple[str, ...] = Field(
+        default=(),
+        description="Sources the profile was assembled from, e.g. '.chipgraph.yml@<commit>'.",
+    )
+    packs: dict[str, str] = Field(default={}, description="Pack ids to their versions.")
+    adapters: dict[str, str] = Field(default={}, description="Adapter ids to their versions.")
+    models: dict[str, str] = Field(default={}, description="Model ids to their versions.")
+    tools: dict[str, str] = Field(default={}, description="EDA tool ids to their versions.")
+    runner: str = Field(default="local", description="The runner used to execute this run.")

chipgraph/core/contracts/export.py

@@ -0,0 +1,128 @@
+"""Export JSON Schema files for the core contracts.
+
+Run as ``python -m chipgraph.core.contracts.export [--check] [--out DIR]``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from chipgraph.core.contracts import TOP_LEVEL_MODELS
+from chipgraph.core.model.export import MODEL_SCHEMA_MODELS
+
+_README_CONTENT = (
+    "# schemas\n"
+    "\n"
+    "These JSON Schema files are generated from the pydantic models in\n"
+    "`src/chipgraph/core/contracts/` by `make schemas`\n"
+    "(`python -m chipgraph.core.contracts.export`). Do not edit them by hand.\n"
+    "\n"
+    "`model/` holds the schemas for the Design Model's entities and relations\n"
+    "(`src/chipgraph/core/model/`).\n"
+)
+
+
+def find_repo_root(start: Path) -> Path:
+    """Walk up from `start` until a directory containing `pyproject.toml` is found."""
+    current = start.resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / "pyproject.toml").is_file():
+            return candidate
+    raise FileNotFoundError(f"no pyproject.toml found above {start}")
+
+
+def generate_schema_files() -> dict[str, str]:
+    """Build the mapping of {relative path: contents} for every schema file to write.
+
+    Core contract schemas are top-level (`ArtifactRef.schema.json`, ...); Design Model
+    schemas live under `model/` (`model/BlockEntity.schema.json`, ...).
+    """
+    files: dict[str, str] = {"README.md": _README_CONTENT}
+    for model in TOP_LEVEL_MODELS:
+        filename = f"{model.__name__}.schema.json"
+        schema = model.model_json_schema()
+        files[filename] = json.dumps(schema, indent=2, sort_keys=True) + "\n"
+    for model_cls in MODEL_SCHEMA_MODELS:
+        filename = f"model/{model_cls.__name__}.schema.json"
+        model_schema = model_cls.model_json_schema()
+        files[filename] = json.dumps(model_schema, indent=2, sort_keys=True) + "\n"
+    return files
+
+
+def write_schema_files(out_dir: Path) -> None:
+    """Write the generated schema files to `out_dir`, creating it (and `model/`) if needed."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for rel_path, content in generate_schema_files().items():
+        path = out_dir / rel_path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+
+
+def check_schema_files(out_dir: Path) -> list[str]:
+    """Compare generated schema files against what's on disk in `out_dir`.
+
+    Returns a list of human-readable problem descriptions; empty means up to date.
+    """
+    expected = generate_schema_files()
+    problems: list[str] = []
+
+    existing_names: set[str] = set()
+    if out_dir.is_dir():
+        existing_names |= {p.name for p in out_dir.glob("*") if p.is_file()}
+        model_dir = out_dir / "model"
+        if model_dir.is_dir():
+            existing_names |= {f"model/{p.name}" for p in model_dir.glob("*") if p.is_file()}
+
+    for rel_path, content in expected.items():
+        path = out_dir / rel_path
+        if not path.is_file():
+            problems.append(f"missing: {rel_path}")
+        elif path.read_text(encoding="utf-8") != content:
+            problems.append(f"outdated: {rel_path}")
+
+    extra_names = existing_names - set(expected)
+    for rel_path in sorted(extra_names):
+        if rel_path.endswith(".schema.json") or rel_path == "README.md":
+            problems.append(f"extra: {rel_path}")
+
+    return problems
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point: regenerate or check the `schemas/` directory."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="check that schemas/ matches the models, without writing; exit 1 if not",
+    )
+    parser.add_argument(
+        "--out",
+        type=Path,
+        default=None,
+        help="output directory (default: schemas/ at the repo root)",
+    )
+    args = parser.parse_args(argv)
+
+    out_dir = args.out if args.out is not None else find_repo_root(Path(__file__)) / "schemas"
+
+    if args.check:
+        problems = check_schema_files(out_dir)
+        if problems:
+            print("schemas out of date:", file=sys.stderr)
+            for problem in problems:
+                print(f"  {problem}", file=sys.stderr)
+            return 1
+        print(f"schemas up to date in {out_dir}")
+        return 0
+
+    write_schema_files(out_dir)
+    print(f"wrote schemas to {out_dir}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

chipgraph/core/contracts/finding.py

@@ -0,0 +1,171 @@
+"""Findings: problems found in the design, at one of 5 layers of certainty (DESIGN.md 4.8).
+
+A `Finding` is the common shape every check, Critic (AI) pass, z3, or formal run reports
+issues in. Evidence is mandatory: a finding with nothing pointing at a file:line or a
+Design Model key is not a finding. AI sources (anything other than the known
+deterministic ones: `check:*`, `z3`, `formal`, `lint`) can never report `severity="error"`,
+so an unreliable finding never blocks a build on its own (DESIGN.md 4.8).
+
+A finding's identity across runs is its `fingerprint`: a stable hash of its source, claim,
+and evidence locations, independent of `first_seen`/`last_seen`/`confidence`. The same
+problem found again by the same source is the same finding, not a new one.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable
+from typing import Literal, Self
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, model_validator
+
+from chipgraph.core.contracts._paths import validate_relative_path
+from chipgraph.core.contracts.artifact import ArtifactRef
+from chipgraph.core.contracts.types import Sha256
+
+FindingSeverity = Literal["error", "warning", "question"]
+"""How serious a finding is. Only deterministic layers may use `error` (DESIGN.md 4.8)."""
+
+FindingStatus = Literal["open", "fixed", "waived"]
+"""A finding's lifecycle: newly (re)detected, no longer detected, or waived by a person."""
+
+_DETERMINISTIC_SOURCES = frozenset({"z3", "formal", "lint"})
+_FINGERPRINT_ID_CHARS = 8
+
+
+def is_ai_source(source: str) -> bool:
+    """Whether `source` is an AI source (Critic or similar), never a deterministic one.
+
+    Deterministic sources are `check:<id>`, `z3`, `formal`, and `lint`. Anything else
+    -- `critic`, or any future AI source id -- is treated as AI, conservatively: an
+    unrecognized source is never assumed safe enough to block a build.
+    """
+    if source.startswith("check:"):
+        return False
+    return source not in _DETERMINISTIC_SOURCES
+
+
+def _artifact_key(ref: ArtifactRef) -> str:
+    return f"{ref.repo}:{ref.path if ref.path is not None else ref.model_key}"
+
+
+def _evidence_key(evidence: Evidence) -> str:
+    if evidence.file is not None:
+        return f"{evidence.file}:{evidence.line if evidence.line is not None else '-'}"
+    return f"model:{evidence.model_key}"
+
+
+def compute_fingerprint(source: str, claim: str, evidence: Iterable[Evidence]) -> str:
+    """A stable sha256 hex digest identifying a finding across runs.
+
+    Built from `source`, `claim`, and the sorted set of evidence locations
+    (`file:line` or `model:<key>`). Deliberately excludes anything that can change
+    run to run without the underlying problem changing: `first_seen`, `last_seen`,
+    `confidence`, `suggestion`, `artifacts`/`artifact_hashes`, `run_id`.
+    """
+    digest = hashlib.sha256()
+    digest.update(source.encode("utf-8"))
+    digest.update(b"\0")
+    digest.update(claim.encode("utf-8"))
+    digest.update(b"\0")
+    for loc in sorted(_evidence_key(e) for e in evidence):
+        digest.update(loc.encode("utf-8"))
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+class Evidence(BaseModel):
+    """A pointer to where a finding was observed: a file:line, or a Design Model key."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    file: str | None = Field(default=None, description="POSIX path, relative to the repo root.")
+    line: int | None = Field(default=None, ge=1, description="1-based line number, if any.")
+    model_key: str | None = Field(
+        default=None, description="Key into the Design Model, when this evidence is not a file."
+    )
+    note: str = Field(default="", description="An optional free-text note about this evidence.")
+
+    @model_validator(mode="after")
+    def _check_exactly_one_locator(self) -> Self:
+        if (self.file is None) == (self.model_key is None):
+            raise ValueError("Evidence needs exactly one of 'file' or 'model_key' to be set")
+        if self.file is not None:
+            validate_relative_path(self.file, field_name="file")
+        elif self.line is not None:
+            raise ValueError("Evidence 'line' requires 'file' to be set")
+        return self
+
+
+class Finding(BaseModel):
+    """A single detected problem, at one of the 5 layers of DESIGN.md 4.8."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    id: str = Field(default="", description="'F-<first 8 chars of fingerprint>'; computed.")
+    fingerprint: str = Field(
+        default="", description="Stable identity hash of source+claim+evidence; computed."
+    )
+    layer: int = Field(ge=1, le=5, description="Which of the 5 layers of DESIGN.md 4.8 found this.")
+    severity: FindingSeverity = Field(description="How serious this finding is.")
+    source: str = Field(
+        description="Where this came from: 'check:<id>', 'critic', 'z3', 'formal', or 'lint'."
+    )
+    evidence: tuple[Evidence, ...] = Field(
+        min_length=1, description="Where this was observed; at least one is required."
+    )
+    claim: str = Field(description="What is wrong, in plain language.")
+    suggestion: str = Field(default="", description="A suggested fix, if any.")
+    confidence: float = Field(default=1.0, ge=0, le=1, description="Confidence in this finding.")
+    status: FindingStatus = Field(default="open", description="This finding's lifecycle status.")
+    artifacts: tuple[ArtifactRef, ...] = Field(
+        default=(), description="Artifacts this finding concerns; what a waiver binds to."
+    )
+    artifact_hashes: dict[str, Sha256] = Field(
+        default={},
+        description="Content hashes of `artifacts` at detection time, keyed by "
+        "'<repo>:<path or model_key>'.",
+    )
+    first_seen: AwareDatetime = Field(description="When this finding (fingerprint) was first seen.")
+    last_seen: AwareDatetime = Field(description="When this finding was last (re)detected.")
+    run_id: str | None = Field(default=None, description="The run that (re)detected this finding.")
+
+    @model_validator(mode="after")
+    def _fill_fingerprint_and_id(self) -> Self:
+        if not self.fingerprint:
+            object.__setattr__(
+                self, "fingerprint", compute_fingerprint(self.source, self.claim, self.evidence)
+            )
+        if not self.id:
+            object.__setattr__(self, "id", f"F-{self.fingerprint[:_FINGERPRINT_ID_CHARS]}")
+        return self
+
+    @model_validator(mode="after")
+    def _check_ai_source_not_error(self) -> Self:
+        if self.severity == "error" and is_ai_source(self.source):
+            raise ValueError(
+                f"source {self.source!r} is an AI source; it cannot report severity='error' "
+                "(DESIGN.md 4.8: AI findings never block, only deterministic layers can)"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_artifact_hashes_match_artifacts(self) -> Self:
+        valid_keys = {_artifact_key(ref) for ref in self.artifacts}
+        for key in self.artifact_hashes:
+            if key not in valid_keys:
+                raise ValueError(
+                    f"artifact_hashes key {key!r} does not match any entry in 'artifacts'"
+                )
+        return self
+
+
+__all__ = [
+    "Evidence",
+    "Finding",
+    "FindingSeverity",
+    "FindingStatus",
+    "compute_fingerprint",
+    "is_ai_source",
+]

chipgraph/core/contracts/gate.py

@@ -0,0 +1,50 @@
+"""Gates: human approval points, and the approvals recorded against them."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+
+from chipgraph.core.contracts.artifact import ArtifactRef
+from chipgraph.core.contracts.types import Sha256
+
+
+class GateSpec(BaseModel):
+    """The specification of a gate: which artifacts need human approval, and how."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    id: str = Field(description="The id of this gate.")
+    artifacts: tuple[ArtifactRef, ...] = Field(
+        min_length=1, description="The artifacts this gate covers."
+    )
+    approvers: tuple[str, ...] = Field(
+        default=(), description="Identities allowed to approve this gate."
+    )
+    mode: Literal["pr", "file"] = Field(default="file", description="How approval is recorded.")
+
+
+class Approval(BaseModel):
+    """A recorded decision against a gate, pinned to the artifact hashes it approved."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    gate_id: str = Field(description="The id of the gate this approval is for.")
+    by: str = Field(description="The identity that made this decision.")
+    at: AwareDatetime = Field(description="When this decision was made.")
+    artifact_hashes: dict[str, Sha256] = Field(
+        min_length=1,
+        description="Hashes the decision was made against, keyed by '<repo>:<path or model_key>'.",
+    )
+    decision: Literal["approve", "reject", "baseline", "waive"] = Field(
+        description="The decision that was made."
+    )
+    note: str = Field(default="", description="An optional free-text note explaining the decision.")
+
+    def is_current(self, current: Mapping[str, str]) -> bool:
+        """Return True only if every hash this approval covers still matches `current`."""
+        return all(current.get(key) == expected for key, expected in self.artifact_hashes.items())

chipgraph/core/contracts/rule.py

@@ -0,0 +1,177 @@
+"""Rules: how artifacts get produced, and instances of rules bound to concrete params."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from chipgraph.core.contracts._paths import validate_relative_path
+from chipgraph.core.contracts.artifact import ArtifactRef
+from chipgraph.core.contracts.types import ModelTier, RuleId, RuleKind
+
+_TIER_ORDER: dict[ModelTier, int] = {"small": 0, "medium": 1, "large": 2}
+
+
+class InputSpec(BaseModel):
+    """A declared input to a rule: where it comes from and how to select it."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    source: Literal["model", "spec", "artifact", "path"] = Field(
+        description="Where this input comes from: the Design Model, a spec, an artifact, or a path."
+    )
+    selector: str = Field(description="A template selecting the input, e.g. 'block/{block}'.")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _accept_short_form(cls, data: Any) -> Any:
+        if (
+            isinstance(data, dict)
+            and len(data) == 1
+            and not (set(data.keys()) & {"source", "selector"})
+        ):
+            ((key, value),) = data.items()
+            if key in ("model", "spec", "artifact", "path"):
+                return {"source": key, "selector": value}
+        return data
+
+
+class Budget(BaseModel):
+    """Resource budget for an agent rule: retries, model tier, and token cap."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    tries: int = Field(default=3, ge=1, description="Maximum number of attempts.")
+    tier: ModelTier = Field(default="medium", description="Model tier to use.")
+    escalate: ModelTier | None = Field(
+        default=None, description="Higher model tier to escalate to after repeated failures."
+    )
+    tokens: int | None = Field(default=None, ge=1, description="Maximum tokens allowed, if capped.")
+
+    @model_validator(mode="after")
+    def _check_escalate_order(self) -> Self:
+        if self.escalate is not None and _TIER_ORDER[self.escalate] <= _TIER_ORDER[self.tier]:
+            raise ValueError(
+                f"escalate tier {self.escalate!r} must be higher than tier {self.tier!r}"
+            )
+        return self
+
+
+_DEFAULT_BUDGET = Budget()
+
+
+class RunSpec(BaseModel):
+    """How a `gen`/`import` rule actually runs: a tool adapter and its arguments."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    use: str = Field(description="The tool adapter to run, e.g. 'cmd'.")
+    args: dict[str, Any] = Field(default={}, description="Arguments passed to the tool adapter.")
+
+
+class RuleSpec(BaseModel):
+    """The specification of a rule: how it produces outputs from inputs."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    id: RuleId = Field(description="Namespaced rule id, e.g. 'digital-rtl/rtl_module'.")
+    kind: RuleKind = Field(description="How this rule produces its outputs.")
+    description: str = Field(
+        default="", description="A short, plain-English description of the rule."
+    )
+    foreach: str | None = Field(
+        default=None,
+        description="A selector this rule is expanded over, e.g. one instance per block.",
+    )
+    inputs: tuple[InputSpec, ...] = Field(default=(), description="The inputs this rule consumes.")
+    outputs: tuple[str, ...] = Field(
+        min_length=1, description="Output path templates this rule produces."
+    )
+    checks: tuple[str, ...] = Field(
+        default=(), description="Check ids run to verify this rule's outputs."
+    )
+    verified_by: RuleId | str | None = Field(
+        default=None, description="A rule or check id that verifies this rule's outputs."
+    )
+    budget: Budget = Field(default_factory=lambda: _DEFAULT_BUDGET, description="Resource budget.")
+    role: str | None = Field(
+        default=None, description="The agent role that runs this rule, if any."
+    )
+    skills: tuple[str, ...] = Field(
+        default=(), description="Skill ids available to the agent role."
+    )
+    gate: str | None = Field(
+        default=None, description="A gate id that must approve before this rule runs."
+    )
+    run: RunSpec | None = Field(
+        default=None,
+        description="How this rule actually runs (kind 'gen'/'import' only): tool adapter + args.",
+    )
+
+    @model_validator(mode="after")
+    def _check_outputs_present(self) -> Self:
+        if len(self.outputs) < 1:
+            raise ValueError("RuleSpec.outputs must have at least one output template")
+        for output in self.outputs:
+            validate_relative_path(output, field_name="outputs")
+        return self
+
+    @model_validator(mode="after")
+    def _check_agent_fields(self) -> Self:
+        if self.kind == "agent":
+            if self.role is None:
+                raise ValueError("RuleSpec with kind='agent' requires 'role'")
+        else:
+            if self.role is not None:
+                raise ValueError("'role' is only allowed when kind='agent'")
+            if self.skills:
+                raise ValueError("'skills' is only allowed when kind='agent'")
+            if self.budget != _DEFAULT_BUDGET:
+                raise ValueError("a non-default 'budget' is only allowed when kind='agent'")
+        return self
+
+    @model_validator(mode="after")
+    def _check_run_field(self) -> Self:
+        if self.run is not None and self.kind not in ("gen", "import"):
+            raise ValueError("'run' is only allowed when kind is 'gen' or 'import'")
+        if self.kind == "gen" and self.run is None:
+            raise ValueError("RuleSpec with kind='gen' requires 'run'")
+        return self
+
+
+class RuleInstance(BaseModel):
+    """A rule bound to concrete parameters, with resolved inputs and outputs."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    rule_id: RuleId = Field(description="The id of the rule this is an instance of.")
+    params: dict[str, str] = Field(
+        default={}, description="Concrete parameter values, e.g. block, module."
+    )
+    inputs: tuple[ArtifactRef, ...] = Field(
+        default=(), description="Resolved input artifact references."
+    )
+    outputs: tuple[ArtifactRef, ...] = Field(
+        min_length=1, description="Resolved output artifact references."
+    )
+    instance_id: str = Field(description="A stable id for this instance, built by make_id().")
+
+    @classmethod
+    def make_id(cls, rule_id: str, params: dict[str, str]) -> str:
+        """Build the stable instance id for a rule id and its parameters."""
+        sorted_params = ",".join(f"{k}={params[k]}" for k in sorted(params))
+        return f"{rule_id}[{sorted_params}]"
+
+    @model_validator(mode="after")
+    def _check_outputs_and_id(self) -> Self:
+        if len(self.outputs) < 1:
+            raise ValueError("RuleInstance.outputs must have at least one output")
+        expected = self.make_id(self.rule_id, self.params)
+        if self.instance_id != expected:
+            raise ValueError(
+                f"instance_id {self.instance_id!r} does not match make_id() result {expected!r}"
+            )
+        return self

chipgraph/core/contracts/types.py

@@ -0,0 +1,45 @@
+"""Shared type aliases and literals used across the core contracts."""
+
+from typing import Annotated, Literal
+
+from pydantic import StringConstraints
+
+DataLabel = Literal["public", "internal", "nda"]
+"""How sensitive an artifact's content is: public, internal-only, or NDA-restricted."""
+
+ArtifactKind = Literal[
+    "spec",
+    "rtl",
+    "tb",
+    "sva",
+    "report",
+    "plan",
+    "model",
+    "doc",
+    "diagram",
+    "script",
+    "config",
+    "other",
+]
+"""The kind of thing an artifact is, independent of its file format."""
+
+RuleKind = Literal["gen", "agent", "human", "import"]
+"""How a rule produces its outputs: a generator, an AI agent, a human, or an import."""
+
+ModelTier = Literal["small", "medium", "large"]
+"""A relative capability/cost tier for an LLM used by an agent rule."""
+
+CheckStatus = Literal["pass", "fail", "error", "skipped"]
+"""The outcome of running a check: it passed, it failed, it errored, or it was skipped."""
+
+Severity = Literal["error", "warning", "info"]
+"""How serious a single check issue is."""
+
+FailureLabel = Literal["context", "constraint", "verification", "planning", "infra"]
+"""A coarse category for why a rule failed, used for run analytics."""
+
+RuleId = Annotated[str, StringConstraints(pattern=r"^[a-z0-9][a-z0-9_-]*/[a-z0-9][a-z0-9_]*$")]
+"""A namespaced rule identifier of the form ``<pack>/<name>``, e.g. ``digital-rtl/rtl_module``."""
+
+Sha256 = Annotated[str, StringConstraints(pattern=r"^[0-9a-f]{64}$")]
+"""A lowercase hex-encoded SHA-256 digest."""