frontmattering 0.4.2__py3-none-any.whl

frontmattering/harness_errors.py

@@ -0,0 +1,555 @@
+"""Fail-closed harness error base classes.
+
+Programming contract:
+- A missing requirement is not a warning.
+- An unknown state is not success.
+- A caught HarnessError must be re-raised, wrapped, or converted into an
+  explicit failure result at a boundary such as a CLI/API response.
+- Do not return success with error details hidden in context.
+- Do not use broad ``except Exception: pass`` around harness validation.
+- Prefer ``fail_closed(...)`` at the point where a contract is violated.
+
+Testing contract:
+- Expected harness/validator failures should raise a HarnessError subclass.
+- Tests can catch ``HarnessError`` to prove fail-closed behavior generically.
+- Tests can assert ``to_dict()`` fields so failures stay actionable.
+- Coded subclasses let tests assert stable recovery IDs without parsing prose.
+- Bare ``Exception``/``ValueError`` means implementation bug, not domain failure.
+
+Error taxonomy authority:
+- All intentional harness/domain error classes should live in this module.
+- Other modules may import and raise these errors, but should not define local
+  HarnessError subclasses.
+- Centralizing the taxonomy prevents fragmented error IDs, duplicated
+  subclasses, inconsistent ``fix`` quality, and agent-invented local errors.
+- Tests should be able to inventory expected domain failures from this module.
+- Ordinary unexpected implementation bugs may still surface as normal Python
+  exceptions; expected domain failures should route through this taxonomy.
+
+Taxonomy shape:
+- Use a small number of broad category subclasses.
+- Use many stable ``error_id`` values for specific failures.
+- Category class means "how callers broadly handle this failure".
+- ``error_id`` means "exact recovery, test, and documentation key".
+- Add a subclass only when catch/handling behavior differs.
+- Add an ``error_id`` when the specific recovery/test/doc message differs.
+- Do not create a new subclass for every individual failure.
+
+Suggested broad categories:
+- ConfigurationError: bad/missing config, schema, manifest, or setup.
+- ValidationFailure: input failed a contract or validator rule.
+- AuthorityError: authority map, ownership, permission, or policy authority.
+- EvidenceError: missing, stale, untrusted, or insufficient evidence.
+- ToolingError: query tool, subprocess, parser, index, or generated artifact.
+- BoundaryError: CLI/API/serialization/boundary contract failure.
+- InternalBugError: invariant broken inside implementation. This is not a
+  HarnessError subclass and should not be caught by domain boundary handlers.
+
+SOLID guardrails:
+- Single responsibility: error classes hold structured failure data and intent.
+  They do not validate, log, render CLI output, write telemetry, or perform
+  recovery.
+- Open/closed: add new domain errors by subclassing or adding stable IDs, not
+  by changing the base contract for each new use case.
+- Liskov substitution: every subclass must remain usable as a HarnessError and
+  must preserve fail-closed semantics.
+- Interface segregation: CLI/HTTP/log/test rendering belongs in boundary
+  helpers, not on every error subclass.
+- Dependency inversion: validators depend on the HarnessError contract;
+  boundary adapters depend on formatting/serialization helpers.
+- Do not make the base class too clever. Error objects are data and intent;
+  boundary adapters decide presentation; validators decide when to fail.
+
+Field contract:
+- ``what``: human-readable failure summary.
+- ``where``: stable code or workflow location that produced the failure.
+- ``why``: consequence or invariant being protected.
+- ``fix``: concrete next action; do not leave users or agents guessing.
+- ``context``: machine-readable evidence for tests, CLIs, logs, and automation.
+
+Motivation:
+A HarnessError is not just an exception. It is a recovery packet. Every
+intentional failure should answer: what happened, where it happened, why it
+matters, what to do next, and what evidence supports that answer.
+
+AI-agent rule:
+If you cannot fill these fields honestly, you probably do not understand the
+failure well enough to continue silently.
+
+Agent-gradient rule:
+Agents tend to choose the shortest local edit that makes the immediate check
+pass. Therefore fail-closed APIs must make explicit failure cheaper than silent
+recovery. Do not rely on exhortation alone. Provide one-line guards, explicit
+Outcome envelopes, runtime boundary checks, and tests/gates that reject silent
+swallow patterns.
+
+Boundary rule:
+- Inside the system: raise.
+- At a CLI/API boundary: serialize the error and return a nonzero/failed result.
+- Never silently downgrade a HarnessError into a warning or success response.
+
+Catch policy:
+- Catch HarnessError only to add context, wrap it, re-raise it, or serialize it
+  at a boundary.
+- Preserve the original cause when wrapping unexpected exceptions.
+
+Data policy:
+- ``context`` must be deterministic, JSON-serializable, and safe to print.
+- Do not put secrets, huge blobs, raw full-file dumps, or nondeterministic data
+  into ``context``.
+- Constructors normalize non-JSON context defensively so error rendering does
+  not fail while reporting an already-failing state.
+- ``where`` should be a stable selector such as module.function or workflow step.
+- ``fix`` should be executable guidance, not vague advice.
+- ``error_id`` values should be stable and namespaced because tests and
+  recovery docs may depend on them.
+
+Good example:
+``IdentifiedHarnessError.fail_closed(error_id="QPV_E_RECEIPT_MISSING", ...)``
+
+Bad examples:
+- ``return {"status": "ok", "error": "receipt missing"}``
+- ``except Exception: pass``
+- ``raise ValueError("bad")`` for an expected domain failure
+
+Cheap honesty API:
+- ``fail("receipt missing", error_cls=EvidenceError, error_id="QPV_E_...")``
+  raises with caller location captured automatically.
+- ``require(condition, "condition failed")`` is an assert-like fail-closed guard.
+- ``value = must(value, "value missing")`` replaces ``if not value: return {}``.
+- ``Ok(value, evidence={...})`` and ``Fail(error)`` are explicit outcome
+  envelopes; there is no empty-dict success inhabitant.
+- ``ensure_outcome(value)`` rejects boundary returns that are not ``Ok`` or
+  ``Fail`` so dynamic code cannot smuggle ``None``, ``{}``, ``[]``, or ``False``
+  through an Outcome contract.
+
+Enforcement loop:
+- Make the loud path the shortest honest code: ``require``/``must``/``fail``.
+- Make clean success carry evidence: ``Ok(value, evidence={...})``.
+- Make failure explicit: ``Fail(HarnessError(...))`` or raise internally.
+- Make boundary silence invalid: ``ensure_outcome`` rejects non-Outcome values.
+- Make silent swallows fail gates: AST/xref rules should flag
+  ``except ...: pass`` and ``except ...: return None/{}/[]`` inside fail-closed
+  zones, while allowing broad catches only in declared boundary adapters.
+- Require negative fixtures for fail-closed functions so a swallow turns the
+  function's own test red instead of hiding behind a green empty result.
+
+This module exists to make silent failure harder than explicit failure.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from dataclasses import dataclass
+from typing import Any, Generic, NoReturn, TypeAlias, TypeVar
+
+T = TypeVar("T")
+
+__all__ = [
+    "HarnessError",
+    "IdentifiedHarnessError",
+    "ConfigurationError",
+    "ValidationFailure",
+    "AuthorityError",
+    "EvidenceError",
+    "ToolingError",
+    "BoundaryError",
+    "InternalBugError",
+    "CodedHarnessError",
+    "Outcome",
+    "Ok",
+    "Fail",
+    "where_here",
+    "fail",
+    "require",
+    "must",
+    "ensure_outcome",
+]
+
+
+def _json_safe(value: Any, seen: set[int] | None = None) -> Any:
+    seen = set() if seen is None else seen
+    if isinstance(value, str | int | float | bool) or value is None:
+        return value
+    marker = id(value)
+    if marker in seen:
+        return "<cycle>"
+    try:
+        seen.add(marker)
+        if isinstance(value, dict):
+            return {str(key): _json_safe(item, seen) for key, item in value.items()}
+        if isinstance(value, list | tuple):
+            return [_json_safe(item, seen) for item in value]
+        if isinstance(value, set | frozenset):
+            return [_json_safe(item, seen) for item in sorted(value, key=repr)]
+        try:
+            json.dumps(value)
+            return value
+        except TypeError:
+            return repr(value)
+    finally:
+        seen.remove(marker)
+
+
+def _normalize_context(context: dict[str, Any] | None) -> dict[str, Any]:
+    if context is None:
+        return {}
+    if not isinstance(context, dict):
+        return {"value": _json_safe(context)}
+    return _json_safe(context)
+
+
+def where_here(skip: int = 1) -> str:
+    """Return a stable best-effort caller selector for fail-closed helpers."""
+    frame = inspect.currentframe()
+    try:
+        for _ in range(skip):
+            if frame is None:
+                return "<unknown>"
+            frame = frame.f_back
+        if frame is None:
+            return "<unknown>"
+        module = frame.f_globals.get("__name__", "<unknown>")
+        function = frame.f_code.co_name
+        return f"{module}.{function}:{frame.f_lineno}"
+    finally:
+        del frame
+
+
+class HarnessError(Exception):
+    """Base class for fail-closed harness exceptions.
+
+    This is a stop signal, not a log message.
+
+    Development rule: raise early when a required condition is missing,
+    ambiguous, stale, or unproven. Silent fallback hides bugs and makes later
+    evidence unreliable.
+
+    AI-agent guidance:
+    - When uncertain, raise or return a structured failure.
+    - Never hide this error to make a workflow appear green.
+    - Catch only to add context, then re-raise or return an explicit failure.
+    - Prefer ``HarnessError.fail_closed(...)`` over ``None``, ``False``, empty
+      dictionaries, guessed defaults, or warning-only results.
+    - Use ``require`` and ``must`` for local guards because they are intentionally
+      cheaper than hand-written silent fallback branches.
+    - For functions that promise an Outcome, return ``Ok`` with evidence or
+      ``Fail`` with a HarnessError; never return an empty container as a fake
+      success state.
+
+    Test-design guidance:
+    - Use ``pytest.raises(HarnessError)`` for expected fail-closed outcomes.
+    - Assert ``what``, ``where``, ``why``, and ``fix`` are populated enough to
+      guide recovery.
+    - Reserve non-HarnessError exceptions for unexpected implementation bugs.
+    - Inventory expected domain subclasses from this module instead of scanning
+      scattered local error classes.
+
+    Recovery-packet guidance:
+    - ``what`` should name the failed condition.
+    - ``where`` should make the failure locatable without a stack trace.
+    - ``why`` should explain the protected invariant or consequence.
+    - ``fix`` should give the next concrete repair action.
+    - ``context`` should carry structured evidence that tests and CLIs can
+      inspect without scraping prose.
+
+    Boundary guidance:
+    - Raise inside validators and harness internals.
+    - Serialize only at CLI/API/process boundaries.
+    - Never report success with error data hidden in the payload.
+    """
+
+    def __init__(
+        self,
+        what: str,
+        where: str,
+        why: str = "",
+        fix: str = "",
+        context: dict[str, Any] | None = None,
+        *,
+        error_id: str | None = None,
+    ) -> None:
+        super().__init__(what)
+        self.what = what
+        self.where = where
+        self.why = why
+        self.fix = fix
+        self.context = _normalize_context(context)
+        self.error_id = error_id
+
+    def __reduce__(self) -> tuple[object, tuple[type["HarnessError"], dict[str, Any]]]:
+        return (_restore_harness_error, (type(self), self.to_dict()))
+
+    def __setstate__(self, state: dict[str, Any]) -> None:
+        self.what = str(state.get("what", ""))
+        self.where = str(state.get("where", ""))
+        self.why = str(state.get("why", ""))
+        self.fix = str(state.get("fix", ""))
+        context = state.get("context", {})
+        self.context = _normalize_context(context if isinstance(context, dict) else {})
+        error_id = state.get("error_id")
+        self.error_id = str(error_id) if error_id else None
+        self.args = (self.what,)
+
+    @classmethod
+    def fail_closed(
+        cls,
+        what: str,
+        where: str,
+        why: str = "",
+        fix: str = "",
+        context: dict[str, Any] | None = None,
+        *,
+        error_id: str | None = None,
+    ) -> NoReturn:
+        """Raise immediately for an unproven or contract-violating state."""
+        raise cls(
+            what,
+            where,
+            why,
+            fix,
+            context,
+            error_id=error_id,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "error_type": self.__class__.__name__,
+            "what": self.what,
+            "where": self.where,
+            "why": self.why,
+            "fix": self.fix,
+            "context": self.context,
+        }
+        if self.error_id:
+            payload["error_id"] = self.error_id
+        return payload
+
+    def __str__(self) -> str:
+        try:
+            return json.dumps(self.to_dict(), sort_keys=True)
+        except (TypeError, ValueError):
+            return f"{self.__class__.__name__}: {self.what} ({self.where})"
+
+
+class IdentifiedHarnessError(HarnessError):
+    """Structured harness error with stable machine-readable error_id.
+
+    Use this pattern when callers need both fail-closed behavior and a stable
+    recovery/classification key. The default development posture remains:
+    construct only when needed for tests or serialization; call
+    ``IdentifiedHarnessError.fail_closed(...)`` when execution must stop.
+
+    Production domain failures should provide ``error_id``. Construction without
+    an error_id remains allowed so category subclasses are substitutable with
+    HarnessError during tests, wrapping, and generic failure handling.
+    """
+
+
+CodedHarnessError = IdentifiedHarnessError
+
+
+class ConfigurationError(IdentifiedHarnessError):
+    """Bad or missing config, schema, manifest, or setup."""
+
+
+class ValidationFailure(IdentifiedHarnessError):
+    """Input failed a contract or validator rule."""
+
+
+class AuthorityError(IdentifiedHarnessError):
+    """Authority map, ownership, permission, or policy authority failure."""
+
+
+class EvidenceError(IdentifiedHarnessError):
+    """Missing, stale, untrusted, or insufficient evidence."""
+
+
+class ToolingError(IdentifiedHarnessError):
+    """Query tool, subprocess, parser, index, or generated artifact failure."""
+
+
+class BoundaryError(IdentifiedHarnessError):
+    """CLI/API/serialization/boundary contract failure."""
+
+
+class InternalBugError(IdentifiedHarnessError):
+    """Invariant broken inside implementation.
+
+    Internal bugs are still HarnessError instances so executable boundaries can
+    serialize them without leaking raw tracebacks. They must remain terminal:
+    callers may report them, but must not launder them into a recoverable GO.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        where: str = "",
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            where,
+            "A kernel invariant or impossible branch was reached.",
+            "Fix the kernel implementation; do not treat this as user-repairable input.",
+            context,
+            error_id="FRONTMATTERING-KERNEL-INTERNAL-BUG",
+        )
+
+
+def fail(
+    what: str,
+    *,
+    error_cls: type[HarnessError] = HarnessError,
+    error_id: str | None = None,
+    where: str | None = None,
+    why: str = "",
+    fix: str = "",
+    context: dict[str, Any] | None = None,
+) -> NoReturn:
+    """Raise a fail-closed HarnessError with automatic caller location."""
+    raise error_cls(
+        what,
+        where or where_here(skip=2),
+        why,
+        fix,
+        context,
+        error_id=error_id,
+    )
+
+
+def require(
+    condition: Any,
+    what: str,
+    *,
+    error_cls: type[HarnessError] = ValidationFailure,
+    error_id: str | None = None,
+    where: str | None = None,
+    why: str = "",
+    fix: str = "",
+    context: dict[str, Any] | None = None,
+) -> None:
+    """Assert-like guard that raises instead of silently returning falsey data."""
+    if not condition:
+        fail(
+            what,
+            error_cls=error_cls,
+            error_id=error_id,
+            where=where or where_here(skip=2),
+            why=why,
+            fix=fix,
+            context=context,
+        )
+
+
+def must(
+    value: T | None,
+    what: str,
+    *,
+    error_cls: type[HarnessError] = EvidenceError,
+    error_id: str | None = None,
+    where: str | None = None,
+    why: str = "",
+    fix: str = "",
+    context: dict[str, Any] | None = None,
+    reject_empty: bool = False,
+) -> T:
+    """Return value or raise fail-closed if it is absent.
+
+    By default only ``None`` is absent, so falsey-but-valid values like ``0`` or
+    ``False`` survive. Set ``reject_empty=True`` for loaders where empty
+    containers/strings are invalid evidence.
+    """
+    if value is None or (reject_empty and not value):
+        fail(
+            what,
+            error_cls=error_cls,
+            error_id=error_id,
+            where=where or where_here(skip=2),
+            why=why,
+            fix=fix,
+            context=context,
+        )
+    return value
+
+
+@dataclass(frozen=True)
+class Ok(Generic[T]):
+    """Explicit success envelope that must carry evidence."""
+
+    value: T
+    evidence: dict[str, Any]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.evidence, dict) or not self.evidence:
+            raise InternalBugError(
+                "Ok outcome requires non-empty evidence",
+                where="harness_errors.Ok.__post_init__",
+            )
+        object.__setattr__(self, "evidence", _normalize_context(self.evidence))
+
+
+@dataclass(frozen=True)
+class Fail:
+    """Explicit failure envelope carrying a structured HarnessError."""
+
+    error: HarnessError
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.error, HarnessError):
+            raise InternalBugError(
+                "Fail outcome requires a HarnessError",
+                where="harness_errors.Fail.__post_init__",
+                context={"actual_type": type(self.error).__name__},
+            )
+
+
+Outcome: TypeAlias = Ok[T] | Fail
+
+
+def ensure_outcome(
+    value: Any,
+    *,
+    where: str | None = None,
+    error_id: str = "HARNESS_E_NON_OUTCOME_RETURN",
+    what: str = "Outcome-returning function returned a non-Outcome value",
+    context: dict[str, Any] | None = None,
+) -> Outcome[Any]:
+    """Return an Outcome or fail closed when a boundary receives silence.
+
+    This is the runtime backstop for dynamic code. Type hints can say a function
+    returns ``Outcome[T]``, but this guard makes the boundary reject accidental or
+    agent-authored returns such as ``None``, ``{}``, ``[]``, or ``False``.
+    """
+    if isinstance(value, (Ok, Fail)):
+        return value
+
+    boundary_context = {
+        "actual_type": type(value).__name__,
+        "actual_repr": repr(value)[:500],
+        "allowed_types": ["Ok", "Fail"],
+    }
+    if context:
+        boundary_context["caller_context"] = _normalize_context(context)
+
+    fail(
+        what,
+        error_cls=BoundaryError,
+        error_id=error_id,
+        where=where or where_here(skip=2),
+        why="Outcome contracts must carry explicit success evidence or structured failure.",
+        fix="Return Ok(value, evidence={...}) or Fail(error); do not return silent falsey values.",
+        context=boundary_context,
+    )
+
+
+def _restore_harness_error(
+    error_cls: type[HarnessError],
+    state: dict[str, Any],
+) -> HarnessError:
+    error = error_cls.__new__(error_cls)
+    Exception.__init__(error, str(state.get("what", "")))
+    error.__setstate__(state)
+    return error

frontmattering/inventory.py

@@ -0,0 +1,83 @@
+"""Read-only deterministic inventory for governed and plain Markdown."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .core import parse_frontmatter
+from .corpus_selection import SelectionResult
+
+
+def _classify(path: Path, *, selected: bool, normalized: str) -> dict[str, Any]:
+    try:
+        raw_bytes = path.read_bytes()
+        raw = raw_bytes.decode("utf-8", errors="strict")
+    except (OSError, UnicodeDecodeError) as exc:
+        return {
+            "path": normalized,
+            "status": "unreadable",
+            "reason_code": "FRONTMATTERING-INVENTORY-UNREADABLE",
+            "selected": selected,
+            "proposed_action": "inspect_encoding_or_permissions",
+            "detail": str(exc),
+        }
+    if not raw_bytes.startswith(b"---"):
+        return {
+            "path": normalized,
+            "status": "plain_markdown_selected" if selected else "markdown_outside_selection",
+            "reason_code": "FRONTMATTERING-INVENTORY-PLAIN-SELECTED" if selected else "FRONTMATTERING-INVENTORY-OUTSIDE-SELECTION",
+            "selected": selected,
+            "proposed_action": "consider_promotion" if selected else "none",
+        }
+    fm, _body, findings = parse_frontmatter(raw)
+    if fm is not None and not findings:
+        status = "governed_valid" if selected else "markdown_outside_selection"
+        return {
+            "path": normalized,
+            "status": status,
+            "reason_code": "FRONTMATTERING-INVENTORY-GOVERNED-VALID" if selected else "FRONTMATTERING-INVENTORY-OUTSIDE-SELECTION",
+            "selected": selected,
+            "proposed_action": "none",
+            "document_id": (fm.get("ai_document_contract") or {}).get("document_id"),
+        }
+    return {
+        "path": normalized,
+        "status": "governed_invalid" if selected else "markdown_outside_selection",
+        "reason_code": "FRONTMATTERING-INVENTORY-GOVERNED-INVALID" if selected else "FRONTMATTERING-INVENTORY-OUTSIDE-SELECTION",
+        "selected": selected,
+        "proposed_action": "repair_frontmatter" if selected else "none",
+        "finding_ids": sorted({getattr(item, "id", str(item)) for item in findings}),
+    }
+
+
+def build_inventory(selection: SelectionResult) -> dict[str, Any]:
+    selected_set = {p.resolve() for p in selection.paths}
+    documents = [
+        _classify(
+            path,
+            selected=path.resolve() in selected_set,
+            normalized=selection.normalized_path(path),
+        )
+        for path in sorted(selection.all_markdown_paths, key=lambda p: selection.normalized_path(p))
+    ]
+    census = {
+        "governed_valid": sum(1 for item in documents if item["status"] == "governed_valid"),
+        "governed_invalid": sum(1 for item in documents if item["status"] == "governed_invalid"),
+        "plain_markdown_selected": sum(1 for item in documents if item["status"] == "plain_markdown_selected"),
+        "markdown_outside_selection": sum(1 for item in documents if item["status"] == "markdown_outside_selection"),
+        "unreadable": sum(1 for item in documents if item["status"] == "unreadable"),
+    }
+    return {
+        "schema_version": "frontmattering_inventory/v0_2",
+        "project": {
+            "project_file": str(selection.project_file.resolve()) if selection.project_file else None,
+            "project_schema": selection.project_schema,
+        },
+        "selection": selection.payload(),
+        "census": census,
+        "documents": documents,
+        "claim_boundary": {
+            "verifies": ["deterministic file and frontmatter classification"],
+            "does_not_verify": ["whether a plain document should become governed"],
+        },
+    }