chipgraph 0.1.0__py3-none-any.whl

chipgraph/core/runtime/roles/spec.py

@@ -0,0 +1,232 @@
+"""`RoleSpec`: one agent role as data (DESIGN.md 5.1, D8).
+
+A role is a system prompt plus a **tool table**: the abstract capabilities it is granted,
+what it may write, what it may read, and its model tier with the tier it escalates to.
+An agent runtime maps the capabilities to its own tools (the runtime `claude-code`
+renders them into its subagent definitions); the engine and the runtime's guard enforce
+the write scope and the read policy.
+
+A role file is markdown with a YAML frontmatter (the fields below, without `prompt`);
+the body is the prompt. The prompt names tools only through placeholders,
+`{tool:<capability>}`, which the runtime replaces with its own tool names, so this data
+stays free of any harness's tool names.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Annotated, Literal, Self
+
+import yaml
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StringConstraints,
+    ValidationError,
+    model_validator,
+)
+
+from chipgraph.core.contracts import ArtifactKind, ModelTier
+
+Capability = Literal[
+    "read_files",
+    "search_files",
+    "write_outputs",
+    "engine_context",
+    "engine_decisions",
+]
+"""An abstract tool capability a role may be granted.
+
+- `read_files`: read a project file by path.
+- `search_files`: list files by pattern and search their content.
+- `write_outputs`: create and edit files (only the task's outputs: the guard enforces it).
+- `engine_context`: ask the engine for the task's context (`get_context`).
+- `engine_decisions`: read the engine's pending multiple-choice questions.
+"""
+
+CAPABILITIES: tuple[Capability, ...] = (
+    "read_files",
+    "search_files",
+    "write_outputs",
+    "engine_context",
+    "engine_decisions",
+)
+"""Every capability, in the order runtimes list their tools."""
+
+WriteScope = Literal["outputs", "plan", "proposal", "none"]
+"""What a role may write: its rule's outputs, only its plan file, only its proposal file,
+or nothing. `plan` and `proposal` rules have exactly one output (the rule validator checks
+it); every write is still bounded by the task's outputs."""
+
+RoleId = Annotated[str, StringConstraints(pattern=r"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$")]
+"""A role id: lower case words joined by `-`, e.g. `author`, `tb-author`."""
+
+_PLACEHOLDER_RE = re.compile(r"\{tool:([a-z_]+)\}")
+
+_TIER_ORDER: dict[ModelTier, int] = {"small": 0, "medium": 1, "large": 2}
+
+
+class RoleError(Exception):
+    """An unknown role, a broken role file, or a rule that breaks its role's tool table."""
+
+
+class ReadPolicy(BaseModel):
+    """What a role may read with its own tools (the engine's context is checked apart)."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    mode: Literal["any", "deny"] = Field(
+        default="any",
+        description="'any': no read restriction; 'deny': never read the kinds and globs below.",
+    )
+    deny_kinds: tuple[ArtifactKind, ...] = Field(
+        default=(),
+        description=(
+            "Artifact kinds the role must not see: every artifact of these kinds in the "
+            "build graph, and the profile's layout paths for them."
+        ),
+    )
+    deny_globs: tuple[str, ...] = Field(
+        default=(), description="Extra repo-relative path globs the role must not read."
+    )
+
+    @model_validator(mode="after")
+    def _check_mode(self) -> Self:
+        denies = bool(self.deny_kinds or self.deny_globs)
+        if self.mode == "any" and denies:
+            raise ValueError("read_policy mode 'any' takes no deny_kinds or deny_globs")
+        if self.mode == "deny" and not denies:
+            raise ValueError("read_policy mode 'deny' needs deny_kinds or deny_globs")
+        return self
+
+
+class RoleSpec(BaseModel):
+    """One agent role: its prompt and its tool table (DESIGN.md 5.1)."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    id: RoleId = Field(description="The role id rules name in `role:`, e.g. 'author'.")
+    description: str = Field(
+        min_length=1,
+        description="One line: what the role does and how it is started. No line breaks.",
+    )
+    prompt: str = Field(
+        min_length=1,
+        description="The role's system prompt; names tools only as {tool:<capability>}.",
+    )
+    default_tier: ModelTier = Field(description="Model tier of the first attempt.")
+    escalate_to: ModelTier | None = Field(
+        default=None, description="Model tier of later attempts, after a rejected one."
+    )
+    tools: tuple[Capability, ...] = Field(
+        description="Abstract capabilities granted; the runtime maps them to its tools."
+    )
+    write_scope: WriteScope = Field(description="What the role may write.")
+    read_policy: ReadPolicy = Field(
+        default_factory=ReadPolicy, description="What the role may read with its own tools."
+    )
+    shell: Literal[False] = Field(
+        default=False, description="Roles never get a shell (the guard refuses one)."
+    )
+    dispatch: bool = Field(
+        default=True,
+        description=(
+            "Whether agent rules may use this role (handed out as tasks); false for a role "
+            "served by another path, such as the fast decision layer."
+        ),
+    )
+    engine_writes: tuple[ArtifactKind, ...] = Field(
+        default=(),
+        description=(
+            "For a role that writes no files (write_scope 'none'): the artifact kinds of the "
+            "one output the engine writes from the role's structured reply. A rule of this "
+            "role then declares exactly that one output; the role itself never writes it."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _check_table(self) -> Self:
+        if "\n" in self.description:
+            raise ValueError("description must be one line")
+        if self.engine_writes and self.write_scope != "none":
+            raise ValueError("engine_writes is only for a role whose write_scope is 'none'")
+        if len(set(self.engine_writes)) != len(self.engine_writes):
+            raise ValueError("engine_writes lists a kind twice")
+        if len(set(self.tools)) != len(self.tools):
+            raise ValueError("tools lists a capability twice")
+        if self.escalate_to is not None and (
+            _TIER_ORDER[self.escalate_to] <= _TIER_ORDER[self.default_tier]
+        ):
+            raise ValueError(
+                f"escalate_to {self.escalate_to!r} must be higher than "
+                f"default_tier {self.default_tier!r}"
+            )
+        writes = "write_outputs" in self.tools
+        if writes != (self.write_scope != "none"):
+            raise ValueError("write_outputs is granted exactly when write_scope is not 'none'")
+        for name in _PLACEHOLDER_RE.findall(self.prompt):
+            if name not in self.tools:
+                raise ValueError(
+                    f"prompt names {{tool:{name}}}, a capability the role is not granted"
+                )
+        return self
+
+    @property
+    def can_read_files(self) -> bool:
+        """Whether the role has its own file-reading or file-search tools."""
+        return "read_files" in self.tools or "search_files" in self.tools
+
+    def render_prompt(self, tool_names: dict[str, tuple[str, ...]]) -> str:
+        """The prompt with each `{tool:<capability>}` replaced by the runtime's tool names."""
+
+        def _replace(match: re.Match[str]) -> str:
+            names = tool_names.get(match.group(1))
+            if not names:
+                raise RoleError(f"role {self.id!r}: no tool for capability {match.group(1)!r}")
+            return ", ".join(f"`{name}`" for name in names)
+
+        return _PLACEHOLDER_RE.sub(_replace, self.prompt)
+
+
+def split_frontmatter(text: str, *, source: str) -> tuple[dict[str, object], str]:
+    """Split a markdown file into its YAML frontmatter mapping and its body."""
+    if not text.startswith("---\n"):
+        raise ValueError(f"{source}: the frontmatter must open with '---' on the first line")
+    head, sep, body = text[4:].partition("\n---\n")
+    if not sep:
+        raise ValueError(f"{source}: the frontmatter is not closed with '---'")
+    data = yaml.safe_load(head)
+    if not isinstance(data, dict):
+        raise ValueError(f"{source}: the frontmatter is not a mapping")
+    text = body.strip("\n")
+    return {str(k): v for k, v in data.items()}, (text + "\n") if text.strip() else ""
+
+
+def parse_role_file(path: Path) -> RoleSpec:
+    """Load one role file (frontmatter + prompt body). Raises `RoleError`."""
+    try:
+        data, body = split_frontmatter(path.read_text(encoding="utf-8"), source=str(path))
+        if "prompt" in data:
+            raise ValueError(f"{path}: the prompt is the file's body, not a frontmatter key")
+        role = RoleSpec.model_validate({**data, "prompt": body})
+    except (OSError, ValueError, ValidationError, yaml.YAMLError) as exc:
+        raise RoleError(f"invalid role file {path}: {exc}") from exc
+    if role.id != path.stem:
+        raise RoleError(f"role file {path} defines role {role.id!r}; name it {role.id}.md")
+    return role
+
+
+__all__ = [
+    "CAPABILITIES",
+    "Capability",
+    "ReadPolicy",
+    "RoleError",
+    "RoleId",
+    "RoleSpec",
+    "WriteScope",
+    "parse_role_file",
+    "split_frontmatter",
+]

chipgraph/core/state/__init__.py

@@ -0,0 +1 @@
+"""Engine state: journal, run directories, locks, and the artifact store."""

chipgraph/core/state/artifacts.py

@@ -0,0 +1,156 @@
+"""Content hashing, data labels, and the file-based artifact store.
+
+Pure Python: no subprocess calls and no knowledge of git or any other VCS. The store
+only ever hashes bytes it reads itself; `chipgraph.adapters.vcs` is what talks to git.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable, Mapping
+from pathlib import Path, PurePosixPath
+
+from chipgraph.core.contracts.artifact import Artifact, ArtifactRef, ProducedBy
+from chipgraph.core.contracts.types import ArtifactKind, DataLabel, Sha256
+
+_CHUNK_SIZE = 1024 * 1024
+
+
+def hash_bytes(data: bytes) -> str:
+    """Return the lowercase hex sha256 digest of `data`."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def hash_file(path: Path) -> str:
+    """Return the lowercase hex sha256 digest of the file at `path`, read in chunks."""
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        while chunk := handle.read(_CHUNK_SIZE):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def hash_inputs(hashes: Iterable[tuple[str, str]]) -> str:
+    """Return a stable sha256 over `(key, hash)` pairs, independent of iteration order.
+
+    Each pair is typically `("<repo>:<path or model_key>", content_hash)`. Pairs are
+    sorted before hashing so the same set of inputs always yields the same digest,
+    regardless of the order they were produced or discovered in.
+    """
+    digest = hashlib.sha256()
+    for key, value in sorted(hashes):
+        digest.update(key.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(value.encode("utf-8"))
+        digest.update(b"\n")
+    return digest.hexdigest()
+
+
+class LabelRules:
+    """Maps a repo-relative path to a `DataLabel` by matching POSIX globs.
+
+    Built from an ordered mapping of `glob -> DataLabel` plus a default label used
+    when nothing matches. The most specific matching glob wins: the longest pattern
+    string; ties are broken by preferring the entry that appears later in `globs`.
+    """
+
+    def __init__(
+        self,
+        globs: Mapping[str, DataLabel] | None = None,
+        *,
+        default: DataLabel = "internal",
+    ) -> None:
+        self._globs: tuple[tuple[str, DataLabel], ...] = tuple((globs or {}).items())
+        self._default = default
+
+    @property
+    def default(self) -> DataLabel:
+        """The label used when no glob matches."""
+        return self._default
+
+    def label_for(self, rel_path: str) -> DataLabel:
+        """Return the label for `rel_path`, applying the most specific matching glob."""
+        path = PurePosixPath(rel_path)
+        best_pattern: str | None = None
+        best_label: DataLabel = self._default
+        for pattern, label in self._globs:
+            if not _glob_matches(path, pattern):
+                continue
+            if best_pattern is None or len(pattern) >= len(best_pattern):
+                best_pattern = pattern
+                best_label = label
+        return best_label
+
+
+def _glob_matches(path: PurePosixPath, pattern: str) -> bool:
+    """Match `path` against a POSIX glob `pattern`, where `**` spans directories."""
+    return path.full_match(pattern)
+
+
+class ArtifactStore:
+    """Reads and hashes file-based artifacts under `root`, applying `labels`."""
+
+    def __init__(self, root: Path, labels: LabelRules, repo: str = ".") -> None:
+        self.root = root
+        self.labels = labels
+        self.repo = repo
+
+    def ref(self, rel_path: str, kind: ArtifactKind) -> ArtifactRef:
+        """Build an `ArtifactRef` for `rel_path`, applying the configured data label."""
+        return ArtifactRef(
+            repo=self.repo,
+            kind=kind,
+            path=rel_path,
+            label=self.labels.label_for(rel_path),
+        )
+
+    def artifact(
+        self,
+        rel_path: str,
+        kind: ArtifactKind,
+        produced_by: ProducedBy | None = None,
+        inputs_hash: Sha256 | None = None,
+    ) -> Artifact:
+        """Build an `Artifact` for `rel_path`, hashing its current content.
+
+        Raises `FileNotFoundError` with a clear message if the file does not exist
+        under `root`.
+        """
+        ref = self.ref(rel_path, kind)
+        full_path = self.root / rel_path
+        if not full_path.is_file():
+            raise FileNotFoundError(
+                f"cannot hash artifact {rel_path!r}: no such file under {self.root}"
+            )
+        return Artifact(
+            ref=ref,
+            content_hash=hash_file(full_path),
+            produced_by=produced_by,
+            inputs_hash=inputs_hash,
+        )
+
+    def exists(self, ref: ArtifactRef) -> bool:
+        """Return whether `ref` currently exists on disk (path-based refs only)."""
+        rel_path = self._require_path(ref)
+        return (self.root / rel_path).is_file()
+
+    def current_hashes(self, refs: Iterable[ArtifactRef]) -> dict[str, str]:
+        """Return `{"<repo>:<path>": content_hash}` for every `ref` that exists.
+
+        Refs whose file is missing are skipped (not included in the result), rather
+        than mapped to an empty-string hash.
+        """
+        result: dict[str, str] = {}
+        for ref in refs:
+            rel_path = self._require_path(ref)
+            full_path = self.root / rel_path
+            if not full_path.is_file():
+                continue
+            result[f"{ref.repo}:{rel_path}"] = hash_file(full_path)
+        return result
+
+    @staticmethod
+    def _require_path(ref: ArtifactRef) -> str:
+        if ref.path is None:
+            raise ValueError("model artifacts are hashed by the Design Model")
+        return ref.path

chipgraph/core/state/backend.py

@@ -0,0 +1,117 @@
+"""State backends: where `.chipgraph/state/` actually lives (DESIGN.md 6.1).
+
+This task implements only the `local` backend, which keeps state on the local disk under
+the project repo, hidden from git via `.git/info/exclude` (never by editing a tracked
+`.gitignore`). The `branch:<name>` (and `repo:...`) backends, which push run state to an
+orphan branch or a separate state repository so a run can be resumed or shared from
+another machine, need git operations and are left to a later task in the adapters layer —
+`chipgraph.core` must not shell out to git (see AGENTS.md: "no subprocess, no git commands
+in this code").
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from chipgraph.core.state.layout import StateLayout
+
+_EXCLUDE_LINE = "/.chipgraph/state/"
+
+
+@runtime_checkable
+class StateBackend(Protocol):
+    """Where a project's run state is stored, and how to make sure it's ready to use."""
+
+    name: str
+
+    def prepare(self) -> None:
+        """Make sure the backend is ready to use (e.g. create directories, hide from git)."""
+        ...
+
+    @property
+    def layout(self) -> StateLayout:
+        """The paths this backend stores state under."""
+        ...
+
+
+def _git_common_dir(root: Path) -> Path | None:
+    """Resolve `root/.git`'s common git dir, without shelling out to git.
+
+    Handles both a plain repo (`.git` is a directory) and a worktree (`.git` is a file
+    containing `gitdir: <path>`, whose target directory has a `commondir` file pointing at
+    the real common git dir, relative to that `gitdir` path).
+    """
+    git_path = root / ".git"
+    if git_path.is_dir():
+        return git_path
+    if not git_path.is_file():
+        return None
+
+    content = git_path.read_text(encoding="utf-8").strip()
+    prefix = "gitdir:"
+    if not content.startswith(prefix):
+        return None
+    gitdir = Path(content[len(prefix) :].strip())
+    if not gitdir.is_absolute():
+        gitdir = (root / gitdir).resolve()
+
+    commondir_file = gitdir / "commondir"
+    if not commondir_file.exists():
+        # Not a linked worktree: gitdir *is* the common dir.
+        return gitdir
+
+    common = Path(commondir_file.read_text(encoding="utf-8").strip())
+    if not common.is_absolute():
+        common = (gitdir / common).resolve()
+    return common
+
+
+class LocalBackend:
+    """Keeps run state on local disk under the project repo, hidden from git.
+
+    `prepare()` creates the state directory and, if the project is a git repo, appends
+    `/.chipgraph/state/` to that repo's `.git/info/exclude` — never to a tracked
+    `.gitignore` — so state never shows up in `git status` for anyone. It is idempotent:
+    calling it again does not duplicate the exclude line or otherwise change tracked files.
+    """
+
+    name = "local"
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self._layout = StateLayout(root)
+
+    @property
+    def layout(self) -> StateLayout:
+        return self._layout
+
+    def prepare(self) -> None:
+        self._layout.state_dir.mkdir(parents=True, exist_ok=True)
+        common_dir = _git_common_dir(self.root)
+        if common_dir is None:
+            return
+        exclude_path = common_dir / "info" / "exclude"
+        exclude_path.parent.mkdir(parents=True, exist_ok=True)
+        existing = ""
+        if exclude_path.exists():
+            existing = exclude_path.read_text(encoding="utf-8")
+        lines = existing.splitlines()
+        if _EXCLUDE_LINE in lines:
+            return
+        with open(exclude_path, "a", encoding="utf-8") as f:
+            if existing and not existing.endswith("\n"):
+                f.write("\n")
+            f.write(_EXCLUDE_LINE + "\n")
+
+
+def backend_from_config(value: str, root: Path) -> StateBackend:
+    """Build a `StateBackend` from a `.chipgraph.yml` `state.backend` value."""
+    if value == "local":
+        return LocalBackend(root)
+    if value.startswith("branch:") or value.startswith("repo:"):
+        raise NotImplementedError(f"state backend {value!r} lands with the git state backend task")
+    raise ValueError(f"unknown state backend: {value!r}")
+
+
+__all__ = ["LocalBackend", "StateBackend", "backend_from_config"]

chipgraph/core/state/findings.py

@@ -0,0 +1,151 @@
+"""The finding store, and how a waiver's currency is computed (DESIGN.md 4.8, 6.1).
+
+Findings are machine-local state, not a repo artifact (DESIGN.md 6.1 "State chạy máy"):
+one JSON file per `fingerprint` under ``<state_dir>/findings/``. A waiver, by contrast,
+is a person's decision and lives in ``.chipgraph/decisions/`` as an `Approval` (through
+the `file` review adapter); this module only defines what a waiver *is* -- an
+`Approval` with `decision == "waive"`, bound by `gate_id` to a finding's id -- and how to
+tell whether one is still current. Actually writing a waiver decision (which needs the
+`ReviewAdapter`) is an app-layer concern (`chipgraph.app.findings.waive`).
+"""
+
+from __future__ import annotations
+
+import builtins
+import os
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+
+from chipgraph.core.contracts import Approval
+from chipgraph.core.contracts.finding import Finding, FindingSeverity, FindingStatus
+from chipgraph.core.state.layout import StateLayout
+
+
+def waiver_gate_id(finding_id: str) -> str:
+    """The `Approval.gate_id` a waiver for `finding_id` is recorded (and looked up) under."""
+    return f"finding:{finding_id}"
+
+
+def effective_status(
+    finding: Finding, waivers: Iterable[Approval], current_hashes: Mapping[str, str]
+) -> FindingStatus:
+    """The finding's status right now, resolving waiver currency against `current_hashes`.
+
+    - `"fixed"` if the stored finding is already marked fixed.
+    - `"waived"` only if at least one of `waivers` has `decision == "waive"` and is
+      still current: every artifact hash it is bound to still matches `current_hashes`
+      (`Approval.is_current`). A waiver bound to a hash that no longer matches -- the
+      artifact changed -- no longer counts: the finding is reported `"open"` again, and
+      the expiry is visible to the caller by simply not finding a current waiver.
+    - `"open"` otherwise.
+    """
+    if finding.status == "fixed":
+        return "fixed"
+    for waiver in waivers:
+        if waiver.decision == "waive" and waiver.is_current(current_hashes):
+            return "waived"
+    return "open"
+
+
+class FindingStore:
+    """Stores `Finding`s as one JSON file per fingerprint, under the state backend."""
+
+    def __init__(self, layout: StateLayout) -> None:
+        self.layout = layout
+        self._dir = layout.state_dir / "findings"
+
+    def _path(self, fingerprint: str) -> Path:
+        return self._dir / f"{fingerprint}.json"
+
+    def get(self, fingerprint: str) -> Finding | None:
+        """Return the stored finding for `fingerprint`, or `None` if there is none."""
+        path = self._path(fingerprint)
+        if not path.is_file():
+            return None
+        return Finding.model_validate_json(path.read_text(encoding="utf-8"))
+
+    def get_by_id(self, finding_id: str) -> Finding | None:
+        """Return the stored finding whose `id` is `finding_id`, or `None`."""
+        for finding in self.list():
+            if finding.id == finding_id:
+                return finding
+        return None
+
+    def _put(self, finding: Finding) -> None:
+        self._dir.mkdir(parents=True, exist_ok=True)
+        path = self._path(finding.fingerprint)
+        tmp_path = path.with_suffix(path.suffix + ".tmp")
+        tmp_path.write_text(finding.model_dump_json(indent=2), encoding="utf-8")
+        os.replace(tmp_path, path)
+
+    def upsert(self, findings: Iterable[Finding]) -> list[Finding]:
+        """Insert or refresh `findings`, keyed by `fingerprint`.
+
+        `last_seen` is taken from each incoming `finding` as given (the caller decides
+        what "now" means, e.g. a run's start time). For a finding already on disk:
+        `first_seen` is kept from the existing record, and `status` is kept as
+        `"waived"` if it already was (a waiver survives re-detection; its currency is
+        decided separately by `effective_status`), otherwise the incoming finding's
+        status is used (so a `"fixed"` finding that is detected again goes back to
+        `"open"`).
+        """
+        stored: list[Finding] = []
+        for finding in findings:
+            existing = self.get(finding.fingerprint)
+            if existing is not None:
+                status = "waived" if existing.status == "waived" else finding.status
+                finding = finding.model_copy(
+                    update={"first_seen": existing.first_seen, "status": status}
+                )
+            self._put(finding)
+            stored.append(finding)
+        return stored
+
+    def list(
+        self,
+        *,
+        status: FindingStatus | None = None,
+        layer: int | None = None,
+        severity: FindingSeverity | None = None,
+        source: str | None = None,
+    ) -> list[Finding]:
+        """Return every stored finding matching the given filters, sorted by `id`."""
+        if not self._dir.is_dir():
+            return []
+        results: list[Finding] = []
+        for path in sorted(self._dir.glob("*.json")):
+            finding = Finding.model_validate_json(path.read_text(encoding="utf-8"))
+            if status is not None and finding.status != status:
+                continue
+            if layer is not None and finding.layer != layer:
+                continue
+            if severity is not None and finding.severity != severity:
+                continue
+            if source is not None and finding.source != source:
+                continue
+            results.append(finding)
+        results.sort(key=lambda f: f.id)
+        return results
+
+    def mark_fixed(
+        self, seen_fingerprints: Iterable[str], *, source: str
+    ) -> builtins.list[Finding]:
+        """Mark open findings from `source` as `"fixed"` when not in `seen_fingerprints`.
+
+        Meant to be called after a full run of `source` over the whole project (e.g.
+        `/audit`, M1-20): any of that source's open findings not rediscovered in this
+        run are no longer present, so they are fixed. Returns the findings that were
+        just marked fixed.
+        """
+        seen = set(seen_fingerprints)
+        fixed: builtins.list[Finding] = []
+        for finding in self.list(source=source, status="open"):
+            if finding.fingerprint in seen:
+                continue
+            updated = finding.model_copy(update={"status": "fixed"})
+            self._put(updated)
+            fixed.append(updated)
+        return fixed
+
+
+__all__ = ["FindingStore", "effective_status", "waiver_gate_id"]