chipgraph 0.1.0__py3-none-any.whl

chipgraph/app/checks.py

@@ -0,0 +1,202 @@
+"""`ProfileCheckRunner`: maps a check id to a project's `.chipgraph.yml` adapter config
+and runs it, satisfying the scheduler's `CheckRunner` protocol.
+
+Backs both `chipgraph check` (run directly, no run id, no caching) and the `checks=`
+argument to `Scheduler` (see `app/build.py`). A run id may be set after construction
+(`chipgraph resume RUN_ID` knows its run id ahead of time); when it is set, results are
+cached in that run's `IdempotencyStore`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from chipgraph.app.context import AppContext
+from chipgraph.app.findings import findings_from_check, layer_for_check
+from chipgraph.core.contracts import CheckResult, CheckSpec, Issue, RuleInstance
+from chipgraph.core.plugin_api.protocols import Check, ToolAdapter
+from chipgraph.core.plugin_api.registry import PluginError
+from chipgraph.core.plugin_api.types import ToolContext
+from chipgraph.core.state.artifacts import hash_inputs
+from chipgraph.core.state.findings import FindingStore
+from chipgraph.core.state.idempotency import IdempotencyStore, make_key
+
+_RUNNER_KEYS = frozenset({"use", "per_block", "severity"})
+"""Adapter-config keys the runner itself reads; they are not passed to the plugin."""
+
+
+_SEVERITY_RANK = {"info": 0, "warning": 1, "error": 2}
+
+
+def _cap_severity(result: CheckResult, cap: object) -> CheckResult:
+    """Apply a profile's `adapters.<id>.severity` cap to `result` (DESIGN.md 4.8).
+
+    A project may run a check at a lower severity while it is not yet expected to pass
+    (e.g. `trace: { severity: warning }` before DV starts). Every issue that points at a
+    file and is above the cap is lowered to it, and a `fail` with no `error` issue left
+    becomes `pass`, so the check reports but does not block. An issue with no file says
+    the check itself could not run (a missing `make` target, an unreadable input); it is
+    not lowered, and neither is a check that returned `error`. A cap that is not one of
+    `error`/`warning`/`info` is ignored.
+    """
+    if not isinstance(cap, str) or cap not in _SEVERITY_RANK or cap == "error":
+        return result
+    if result.status == "error":
+        return result
+    limit = _SEVERITY_RANK[cap]
+    issues = tuple(
+        issue.model_copy(update={"severity": cap})
+        if issue.file is not None and _SEVERITY_RANK[issue.severity] > limit
+        else issue
+        for issue in result.issues
+    )
+    status = result.status
+    if status == "fail" and not any(i.severity == "error" for i in issues):
+        status = "pass"
+    return result.model_copy(update={"issues": issues, "status": status})
+
+
+class ProfileCheckRunner:
+    """Runs a check id through the adapter `.chipgraph.yml` configures for it."""
+
+    def __init__(
+        self,
+        ctx: AppContext,
+        *,
+        run_id: str | None = None,
+        root_override: Path | None = None,
+    ) -> None:
+        self.ctx = ctx
+        self.run_id = run_id
+        self.finding_store = FindingStore(ctx.layout)
+        self._root = root_override if root_override is not None else ctx.root
+
+    async def run(self, check_id: str, instance: RuleInstance) -> CheckResult:
+        resolved = self.ctx.require_profile()
+        block = instance.params.get("block")
+        profile = resolved.for_block(block) if block is not None else resolved.profile
+
+        cfg = profile.adapters.get(check_id)
+        if cfg is None:
+            return self._record(
+                check_id,
+                CheckResult(
+                    check_id=check_id,
+                    status="error",
+                    issues=(
+                        Issue(
+                            severity="error",
+                            msg=(
+                                f"no adapter configured for check {check_id!r}; "
+                                f"configured adapters: {sorted(profile.adapters)}"
+                            ),
+                        ),
+                    ),
+                    duration_s=0.0,
+                    idempotency_key=make_key({"check_id": check_id, "error": "unknown-check"}),
+                ),
+            )
+
+        plugin = self._resolve_plugin(cfg.use)
+        if plugin is None:
+            return self._record(
+                check_id,
+                CheckResult(
+                    check_id=check_id,
+                    status="error",
+                    issues=(
+                        Issue(
+                            severity="error",
+                            msg=(
+                                f"no check or tool adapter named {cfg.use!r} "
+                                f"(configured for check {check_id!r})"
+                            ),
+                        ),
+                    ),
+                    duration_s=0.0,
+                    idempotency_key=make_key(
+                        {"check_id": check_id, "error": "unknown-adapter", "use": cfg.use}
+                    ),
+                ),
+            )
+
+        args = {k: v for k, v in cfg.model_dump().items() if k not in _RUNNER_KEYS}
+        spec = CheckSpec(id=check_id, capability=check_id, adapter=cfg.use, args=args)
+        tool_ctx = ToolContext(
+            repo_root=self._root,
+            runner=self.ctx.registry.get("runner", "local"),
+            env=dict(profile.env.vars),
+            params=dict(instance.params),
+        )
+
+        # Idempotent resume (DESIGN.md 6.2): a `pass` result is reused when the same
+        # check runs again in the same run with the same files. Only plugins with a
+        # `key_for(spec, ctx)` (today `CmdTool`) can be keyed before running; the
+        # built-in checks fold the files they read into their key inside `run()`, so
+        # they always run. The cache key adds the hashes of the instance's inputs and
+        # outputs, so editing a file between a kill and `resume` runs the check again.
+        # Failures are never reused: a fixed file must be checked again.
+        store = IdempotencyStore(self.ctx.layout, self.run_id) if self.run_id is not None else None
+        key_for = getattr(plugin, "key_for", None)
+        cache_key: str | None = None
+        if store is not None and callable(key_for):
+            refs = [r for r in (*instance.inputs, *instance.outputs) if r.path is not None]
+            files = self.ctx.store.current_hashes(refs)
+            cache_key = make_key(
+                {"check": str(key_for(spec, tool_ctx)), "files": hash_inputs(files.items())}
+            )
+            cached = store.get(cache_key)
+            if cached is not None and cached.ok:
+                return self._record(
+                    check_id, _cap_severity(cached, cfg.model_dump().get("severity"))
+                )
+
+        result = await plugin.run(spec, tool_ctx)
+
+        if store is not None and cache_key is not None and result.ok:
+            store.put(result.model_copy(update={"idempotency_key": cache_key}))
+
+        return self._record(check_id, _cap_severity(result, cfg.model_dump().get("severity")))
+
+    def _record(self, check_id: str, result: CheckResult) -> CheckResult:
+        """Record `result`'s issues as findings, never failing the check for it.
+
+        Only an `OSError` writing to the finding store is swallowed; anything else
+        (e.g. a bug building a `Finding`) is a real error and propagates.
+        """
+        try:
+            layer = layer_for_check(check_id, result.check_id)
+            findings = findings_from_check(
+                result, layer=layer, store=self.ctx.store, run_id=self.run_id
+            )
+            if findings:
+                self.finding_store.upsert(findings)
+        except OSError:
+            pass
+        return result
+
+    def runs_per_block(self, check_id: str) -> bool:
+        """Whether `chipgraph check` runs `check_id` once per block (the default).
+
+        A profile's `adapters.<id>.per_block` wins; otherwise the plugin's own `per_block`
+        attribute (chip-wide checks set it to False); otherwise True.
+        """
+        cfg = self.ctx.require_profile().profile.adapters.get(check_id)
+        if cfg is None:
+            return True
+        override = cfg.model_dump().get("per_block")
+        if isinstance(override, bool):
+            return override
+        plugin = self._resolve_plugin(cfg.use)
+        return bool(getattr(plugin, "per_block", True))
+
+    def _resolve_plugin(self, use: str) -> Check | ToolAdapter | None:
+        for kind in ("check", "tool"):
+            try:
+                return self.ctx.registry.get(kind, use)  # type: ignore[no-any-return]
+            except PluginError:
+                continue
+        return None
+
+
+__all__ = ["ProfileCheckRunner"]

chipgraph/app/context.py

@@ -0,0 +1,191 @@
+"""`AppContext`: everything a CLI command needs, wired up from a project's `.chipgraph.yml`.
+
+Read-only commands (`status`, `doctor`, `config show`, ...) must work even when no profile
+exists yet (DESIGN.md 8.4/6.1): `AppContext.load` always succeeds, and only writes to disk
+(state directory, git exclude) when a profile was actually found. Commands that need a
+profile call `require_profile()`, which raises a clear `AppError`.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from chipgraph.adapters.review.file import FileReview, ReviewError
+from chipgraph.adapters.review.github import GitHubReview
+from chipgraph.app.errors import AppError
+from chipgraph.core.config.errors import ConfigError
+from chipgraph.core.config.loader import ResolvedProfile
+from chipgraph.core.config.loader import load as load_profile
+from chipgraph.core.config.models import DataCfg, Profile
+from chipgraph.core.engine.gate import GateEvaluator
+from chipgraph.core.plugin_api.local import LocalPluginRecord, load_local_plugins
+from chipgraph.core.plugin_api.registry import PluginError, Registry
+from chipgraph.core.state.artifacts import ArtifactStore, LabelRules
+from chipgraph.core.state.backend import LocalBackend
+from chipgraph.core.state.layout import StateLayout
+
+
+def find_repo_root(start: Path) -> Path:
+    """The nearest ancestor of `start` containing `.git`, or `start` itself if none.
+
+    Mirrors `chipgraph.core.config.loader.find_profile`'s own boundary, but always
+    returns a directory (never `None`): a project root is needed even when no profile
+    exists yet, so read-only commands (and `init`) have somewhere to work from.
+    """
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+    walker = current
+    while True:
+        if (walker / ".git").exists():
+            return walker
+        parent = walker.parent
+        if parent == walker:
+            return current
+        walker = parent
+
+
+@dataclass
+class AppContext:
+    """Everything wired up for one CLI invocation: profile, state, store, registry, ..."""
+
+    root: Path
+    resolved: ResolvedProfile | None
+    layout: StateLayout
+    store: ArtifactStore
+    registry: Registry
+    review: FileReview
+    gates: GateEvaluator
+    backend: LocalBackend | None = None
+    local_plugins: tuple[LocalPluginRecord, ...] = ()
+    pr_review: GitHubReview | None = None
+    """The PR review adapter when the profile selects `review: {use: github}`; `review`
+    stays the `file` adapter, which keeps waivers, baselines and light gates."""
+
+    @property
+    def profile(self) -> Profile | None:
+        """The resolved project profile, or `None` if no `.chipgraph.yml` was found."""
+        return self.resolved.profile if self.resolved is not None else None
+
+    def require_profile(self) -> ResolvedProfile:
+        """Return the resolved profile, or raise `AppError` if there is none."""
+        if self.resolved is None:
+            raise AppError("no .chipgraph.yml: only read-only commands work; run `chipgraph init`")
+        return self.resolved
+
+    @classmethod
+    def load(cls, start: Path, *, profile_path: Path | None = None) -> AppContext:
+        """Build an `AppContext` for a command starting at `start`.
+
+        `start` is searched upward for `.chipgraph.yml` (or `profile_path` is used
+        directly); the project root is the nearest git root above `start` (or `start`
+        itself, if it is not inside a git repo). State is only written to disk (state
+        directory created, `.git/info/exclude` updated) when a profile was found.
+        """
+        root = find_repo_root(start)
+        try:
+            resolved = load_profile(start, profile_path=profile_path)
+        except ConfigError as exc:
+            raise AppError(str(exc)) from exc
+
+        layout = StateLayout(root)
+        backend: LocalBackend | None = None
+        if resolved is not None:
+            backend = LocalBackend(root)
+            backend.prepare()
+
+        data_cfg = resolved.profile.data if resolved is not None else DataCfg()
+        labels = LabelRules(dict.fromkeys(data_cfg.nda_paths, "nda"), default=data_cfg.default)
+        store = ArtifactStore(root, labels)
+
+        registry = Registry()
+        try:
+            registry.discover()
+        except PluginError as exc:
+            raise AppError(str(exc)) from exc
+
+        local_plugins = cls._load_local_plugins(root, resolved, registry)
+
+        review = FileReview(layout.decisions_dir)
+        gates = GateEvaluator(review, store)
+
+        pr_review: GitHubReview | None = None
+        review_cfg = resolved.profile.review if resolved is not None else None
+        if review_cfg is not None and review_cfg.use == "github":
+            try:
+                pr_review = GitHubReview.from_config(review_cfg, state_dir=layout.state_dir)
+            except ReviewError as exc:
+                raise AppError(f"review: {exc}") from exc
+
+        return cls(
+            root=root,
+            resolved=resolved,
+            layout=layout,
+            store=store,
+            registry=registry,
+            review=review,
+            gates=gates,
+            backend=backend,
+            local_plugins=local_plugins,
+            pr_review=pr_review,
+        )
+
+    @staticmethod
+    def _load_local_plugins(
+        root: Path, resolved: ResolvedProfile | None, registry: Registry
+    ) -> tuple[LocalPluginRecord, ...]:
+        """Load the profile's local plugins into `registry`, honouring policy and env.
+
+        Disabled either by `policy.local_plugins: deny` (an org may turn it off) or by the
+        `CHIPGRAPH_LOCAL_PLUGINS=0` personal safety switch; the env switch can only disable,
+        never enable. A `PluginError` while loading becomes an `AppError`.
+        """
+        if resolved is None or not resolved.profile.plugins:
+            return ()
+
+        entries = resolved.profile.plugins
+        disabled_reason: str | None = None
+        if resolved.profile.policy.local_plugins == "deny":
+            source = resolved.provenance.get("policy.local_plugins")
+            where = source.location if source is not None else "profile"
+            disabled_reason = f"disabled by {where}"
+        elif os.environ.get("CHIPGRAPH_LOCAL_PLUGINS") == "0":
+            disabled_reason = "disabled by CHIPGRAPH_LOCAL_PLUGINS=0"
+
+        try:
+            return load_local_plugins(
+                root,
+                entries,
+                registry,
+                enabled=disabled_reason is None,
+                disabled_reason=disabled_reason,
+            )
+        except PluginError as exc:
+            raise AppError(str(exc)) from exc
+
+
+def default_identity() -> str:
+    """The identity to attribute a decision to when `--by` is not given.
+
+    `git config user.name`, falling back to the `$USER` environment variable, then
+    `"unknown"`. Never raises: a missing/broken `git` just falls through.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "config", "user.name"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        result = None
+    if result is not None and result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip()
+    return os.environ.get("USER", "unknown")
+
+
+__all__ = ["AppContext", "default_identity", "find_repo_root"]

chipgraph/app/errors.py

@@ -0,0 +1,11 @@
+"""`AppError`: raised for application-layer problems the CLI reports as a usage error."""
+
+from __future__ import annotations
+
+
+class AppError(Exception):
+    """A problem wiring the engine to a concrete project: bad profile, missing pack,
+    missing adapter, no profile for a command that needs one, and so on.
+
+    The CLI catches this (and `chipgraph.core.config.errors.ConfigError`) and exits 2.
+    """

chipgraph/app/executors.py

@@ -0,0 +1,79 @@
+"""`Executor`s for the scheduler: one per `RuleKind` (DESIGN.md 3.3, 3.4).
+
+`gen` and `import` rules run through a tool adapter (`rule.run`); `human` rules just
+check whether their outputs exist yet; `agent` rules use the scheduler's own
+`AgentStub` (agent rules arrive in M2).
+"""
+
+from __future__ import annotations
+
+from chipgraph.app.context import AppContext
+from chipgraph.core.contracts import CheckSpec, RuleInstance, RuleSpec
+from chipgraph.core.contracts.types import FailureLabel
+from chipgraph.core.engine.scheduler import ExecOutcome
+from chipgraph.core.plugin_api.registry import PluginError
+from chipgraph.core.plugin_api.types import ToolContext
+
+
+class RunExecutor:
+    """Runs a `gen`/`import` rule's `run` spec through a tool adapter."""
+
+    def __init__(self, ctx: AppContext) -> None:
+        self.ctx = ctx
+
+    async def execute(self, rule: RuleSpec, instance: RuleInstance) -> ExecOutcome:
+        if rule.run is None:
+            return ExecOutcome(
+                ok=False, failure_label="infra", message=f"rule {rule.id!r} has no 'run'"
+            )
+
+        try:
+            tool = self.ctx.registry.get("tool", rule.run.use)
+        except PluginError as exc:
+            return ExecOutcome(ok=False, failure_label="infra", message=str(exc))
+
+        spec = CheckSpec(
+            id=rule.id, capability=rule.kind, adapter=rule.run.use, args=dict(rule.run.args)
+        )
+        env = dict(self.ctx.profile.env.vars) if self.ctx.profile is not None else {}
+        tool_ctx = ToolContext(
+            repo_root=self.ctx.root,
+            runner=self.ctx.registry.get("runner", "local"),
+            env=env,
+            params=dict(instance.params),
+        )
+
+        result = await tool.run(spec, tool_ctx)
+        if result.status != "pass":
+            label: FailureLabel = "verification" if result.status == "fail" else "infra"
+            message = (
+                "; ".join(issue.msg for issue in result.issues)
+                or result.log_tail
+                or f"tool {rule.run.use!r} did not pass for rule {rule.id!r}"
+            )
+            return ExecOutcome(ok=False, failure_label=label, message=message)
+        return ExecOutcome(ok=True)
+
+
+class HumanExecutor:
+    """A `human` rule 'runs' by having a person write its outputs by hand."""
+
+    def __init__(self, ctx: AppContext) -> None:
+        self.ctx = ctx
+
+    async def execute(self, rule: RuleSpec, instance: RuleInstance) -> ExecOutcome:
+        missing = [
+            ref.path
+            for ref in instance.outputs
+            if ref.path is not None and not self.ctx.store.exists(ref)
+        ]
+        if missing:
+            return ExecOutcome(
+                ok=False,
+                failure_label="planning",
+                message=f"waiting for a person to write {', '.join(missing)}",
+            )
+        return ExecOutcome(ok=True)
+
+
+__all__ = ["HumanExecutor", "RunExecutor"]

chipgraph/app/findings.py

@@ -0,0 +1,203 @@
+"""App-layer glue for findings: `CheckResult` -> `Finding`, and waiving a finding.
+
+Core (`chipgraph.core.contracts.finding`, `chipgraph.core.state.findings`) defines what a
+finding and a waiver are; this module wires them to the rest of the app: mapping a check
+id to a DESIGN.md 4.8 layer, turning a check's `Issue`s into `Finding`s, and recording a
+waiver decision through the `ReviewAdapter` (`chipgraph.adapters.review.file.FileReview`).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable, Mapping
+from datetime import UTC, datetime
+
+from chipgraph.app.errors import AppError
+from chipgraph.core.contracts import Approval, ArtifactRef, CheckResult
+from chipgraph.core.contracts.finding import Evidence, Finding, FindingSeverity
+from chipgraph.core.plugin_api.protocols import ReviewAdapter
+from chipgraph.core.state.artifacts import ArtifactStore
+from chipgraph.core.state.findings import FindingStore, waiver_gate_id
+
+# Layer per DESIGN.md 4.8's table, keyed by check id (falling back to capability, then to
+# layer 1, "cấu trúc và số liệu", which is where most cross-artifact checks land). Checks
+# not listed here (including ones not yet built, e.g. M1-07/M1-19) default to layer 1;
+# add them here as they are built if they belong to a different layer.
+LAYER_BY_CHECK: Mapping[str, int] = {
+    # layer 1: structural/deterministic cross-checks
+    "spec_schema": 1,
+    "cross_chip": 1,
+    "ports_diff": 1,
+    "hardcode": 1,
+    "duplicate": 1,
+    "connect": 1,
+    "cdc_struct": 1,
+    # layer 4: lint / synth "smells"
+    "lint": 4,
+    "layout": 4,
+    "synth": 4,
+    "naming": 4,
+    # layer 5: process (traceability, staleness, gate/approval hygiene)
+    "trace": 5,
+}
+_DEFAULT_LAYER = 1
+
+
+def layer_for_check(check_id: str, capability: str = "") -> int:
+    """The DESIGN.md 4.8 layer a check's findings belong to, defaulting to layer 1."""
+    if check_id in LAYER_BY_CHECK:
+        return LAYER_BY_CHECK[check_id]
+    if capability in LAYER_BY_CHECK:
+        return LAYER_BY_CHECK[capability]
+    return _DEFAULT_LAYER
+
+
+def _finding_severity(issue_severity: str) -> FindingSeverity:
+    # `Issue.severity` is "error" | "warning" | "info"; `Finding.severity` has no "info".
+    if issue_severity == "info":
+        return "warning"
+    if issue_severity == "error":
+        return "error"
+    return "warning"
+
+
+def findings_from_check(
+    result: CheckResult,
+    *,
+    layer: int = 1,
+    store: ArtifactStore | None = None,
+    run_id: str | None = None,
+) -> list[Finding]:
+    """Build one `Finding` per `Issue` in `result`.
+
+    An issue with a `file` gets that as its evidence's `file`/`line`; if `store` is
+    given, the file's current content hash is recorded in `artifacts`/`artifact_hashes`
+    (what a waiver against this finding would bind to). An issue with no `file` (e.g. a
+    whole-check configuration error) has nowhere else to point at, so its evidence uses
+    the check id itself as a Design-Model-style key: `model_key="check:<check_id>"`.
+
+    All findings from a check are deterministic (`source="check:<check_id>"`), so they
+    may carry `severity="error"`.
+    """
+    now = datetime.now(UTC)
+    findings: list[Finding] = []
+    for issue in result.issues:
+        if issue.file is not None:
+            evidence = Evidence(file=issue.file, line=issue.line, note=issue.rule)
+            artifacts: tuple[ArtifactRef, ...] = (ArtifactRef(kind="other", path=issue.file),)
+            artifact_hashes = store.current_hashes(artifacts) if store is not None else {}
+        else:
+            evidence = Evidence(model_key=f"check:{result.check_id}", note=issue.rule)
+            artifacts = ()
+            artifact_hashes = {}
+
+        findings.append(
+            Finding(
+                layer=layer,
+                severity=_finding_severity(issue.severity),
+                source=f"check:{result.check_id}",
+                evidence=(evidence,),
+                claim=issue.msg,
+                artifacts=artifacts,
+                artifact_hashes=artifact_hashes,
+                first_seen=now,
+                last_seen=now,
+                run_id=run_id,
+            )
+        )
+    return findings
+
+
+ABSENT_HASH = hashlib.sha256(b"chipgraph:absent-file").hexdigest()
+"""The hash a waiver records for a bound file that does not exist yet.
+
+When the file appears, its real hash differs, so the waiver stops being current."""
+
+
+def bound_hashes(store: ArtifactStore, paths: Iterable[str]) -> dict[str, str]:
+    """`{"<repo>:<path>": hash}` for `paths`, with `ABSENT_HASH` for a missing file."""
+    refs = [ArtifactRef(kind="other", path=path) for path in paths]
+    present = store.current_hashes(refs)
+    return {
+        f"{ref.repo}:{ref.path}": present.get(f"{ref.repo}:{ref.path}", ABSENT_HASH) for ref in refs
+    }
+
+
+def finding_current_hashes(
+    store: ArtifactStore, finding: Finding, waivers: Iterable[Approval]
+) -> dict[str, str]:
+    """The current hashes to judge `finding`'s waivers against.
+
+    The finding's own artifacts, plus every file a waiver was bound to with `--bind`
+    (a missing one hashes to `ABSENT_HASH`), so a waiver on a whole-check finding
+    expires when a bound file appears or changes.
+    """
+    current = store.current_hashes(finding.artifacts)
+    extra = sorted(
+        key.partition(":")[2]
+        for waiver in waivers
+        for key in waiver.artifact_hashes
+        if key not in current and key.partition(":")[2]
+    )
+    current.update(bound_hashes(store, extra))
+    return current
+
+
+def waive(
+    finding: Finding,
+    *,
+    by: str,
+    reason: str,
+    store: FindingStore,
+    review: ReviewAdapter,
+    current_hashes: Mapping[str, str] | None = None,
+) -> Finding:
+    """Waive `finding`: record a `waive` decision through `review`, bound to its artifacts.
+
+    `reason` is required (an empty reason is refused) and is stored as the decision's
+    `note`. The waiver's `artifact_hashes` come from `finding.artifact_hashes` (its
+    hashes at detection time), unless `current_hashes` is given, in which case the
+    waiver binds to `finding.artifacts`' *current* hashes instead (waiving as of now,
+    not as of whenever the finding was first recorded). A finding with no file (a
+    whole-check error) is bound with `current_hashes` from `bound_hashes` instead (the
+    CLI's `--bind`). Raises `ValueError` if `reason` is blank, or `AppError` if there is
+    no artifact hash to bind a waiver to.
+
+    Also updates the finding's stored `status` to `"waived"` in `store`, for display
+    convenience; `chipgraph.core.state.findings.effective_status` remains the source of
+    truth for whether the waiver is still current.
+    """
+    if not reason.strip():
+        raise ValueError("a waiver requires a non-empty reason")
+
+    hashes = dict(current_hashes) if current_hashes else dict(finding.artifact_hashes)
+    if not hashes:
+        raise AppError(
+            f"cannot waive finding {finding.id!r}: it has no file to bind the waiver to; "
+            "name the files whose change should end the waiver with --bind PATH"
+        )
+
+    approval = Approval(
+        gate_id=waiver_gate_id(finding.id),
+        by=by,
+        at=datetime.now(UTC),
+        artifact_hashes=hashes,
+        decision="waive",
+        note=reason,
+    )
+    review.record(approval)
+
+    updated = finding.model_copy(update={"status": "waived"})
+    (stored,) = store.upsert((updated,))
+    return stored
+
+
+__all__ = [
+    "ABSENT_HASH",
+    "LAYER_BY_CHECK",
+    "bound_hashes",
+    "finding_current_hashes",
+    "findings_from_check",
+    "layer_for_check",
+    "waive",
+]