frontmattering 0.4.2__py3-none-any.whl

frontmattering/ai_instruction_risk.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Any
+
+_PATTERNS = (
+    "ignore previous instructions",
+    "ignore all previous instructions",
+    "reveal the system prompt",
+    "reveal hidden prompt",
+    "override system instructions",
+    "disregard previous instructions",
+    "you are now",
+    "execute this command",
+)
+
+
+def scan_ai_instruction_risk(body: str, structure: dict[str, Any]) -> dict[str, Any]:
+    """Return advisory literal-pattern findings; never claims malicious intent."""
+    code_ranges = []
+    for item in structure.get("code_blocks", []):
+        try:
+            code_ranges.append((int(item["start_line"]), int(item["end_line"])))
+        except (KeyError, TypeError, ValueError):
+            continue
+    findings = []
+    for line_no, line in enumerate(body.splitlines(), start=1):
+        folded = line.casefold()
+        for pattern in _PATTERNS:
+            if pattern in folded:
+                context = "fenced_code" if any(start <= line_no <= end for start, end in code_ranges) else "prose"
+                findings.append({
+                    "finding_id": "FRONTMATTERING-AI-INSTRUCTION-RISK-LITERAL-PATTERN",
+                    "pattern": pattern,
+                    "line": line_no,
+                    "structural_context": context,
+                    "severity": "informational" if context == "fenced_code" else "advisory",
+                    "handling": "treat_as_data_not_instruction",
+                    "claim_boundary": {
+                        "does_not_establish": ["malicious intent", "successful prompt injection", "document unsafety"]
+                    },
+                })
+    return {
+        "scan_state": "COMPLETE",
+        "method": "bounded_literal_pattern_advisory",
+        "findings": findings,
+        "finding_count": len(findings),
+        "claim_boundary": {
+            "establishes": ["presence of configured literal instruction-risk patterns"],
+            "does_not_establish": ["semantic prompt-injection detection", "malicious intent", "safe AI execution"],
+        },
+    }

frontmattering/authoring.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Iterable
+import yaml
+
+from .core import parse_frontmatter
+from .harness_errors import ToolingError
+from .corpus_selection import PROJECT_SCHEMA, load_project as load_selection_project
+
+SCHEMA_VERSION = "frontmattering_frontmatter/v0_1_5"
+TEMPLATE_SCHEMA = "frontmattering_template_use/v0_1_5"
+
+PROFILES = {
+    "router": ("orientation", "package_router", "orientation_only", "AUTHORED_DRAFT", "orientation_router/default"),
+    "guide": ("guide", "authoring_guide", "advisory", "AUTHORED_DRAFT", "frontmattering_authoring_guide/v0_1_5"),
+    "spec": ("specification", "normative_kernel_spec", "normative", "AUTHORED_NORMATIVE_DRAFT_CANDIDATE", "frontmattering_normative_spec/v0_1_5"),
+    "contract": ("implementation_contract", "implementation_contract", "binding_when_explicitly_invoked", "AUTHORED_CANDIDATE", "frontmattering_implementation_contract/v0_1_5"),
+    "evidence": ("evidence_record", "evidence_record", "evidence_record", "EVIDENCE_RECORD_ONLY", "frontmattering_evidence/v0_1_5"),
+    "release": ("release_record", "release_metadata", "release_metadata", "RELEASE_METADATA_ONLY", "frontmattering_release/v0_1_5"),
+    "registry": ("registry_definition", "registry_definition", "advisory", "AUTHORED_DRAFT", "frontmattering_registry/v0_1_5"),
+}
+BUILTIN_SKIP_TAGS = {"unrelated_document_set"}
+
+
+def slug(value: str) -> str:
+    return re.sub(r"[^A-Z0-9]+", "-", value.upper()).strip("-") or "DOC"
+
+
+def project_file(start: Path) -> Path | None:
+    cur = start.resolve()
+    if cur.is_file():
+        cur = cur.parent
+    for p in (cur, *cur.parents):
+        candidate = p / ".frontmattering" / "project.yaml"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def load_project(start: Path) -> dict[str, Any]:
+    p = project_file(start)
+    if p is None:
+        raise ToolingError(
+            "Frontmattering project not initialized",
+            str(start),
+            "No .frontmattering/project.yaml was found in this directory or its parents.",
+            "Run `frontmattering init <directory> --set-id <ID> --title <TITLE>` first.",
+            error_id="FRONTMATTERING-AUTHORING-PROJECT-MISSING",
+        )
+    return load_selection_project(p)
+
+
+def _project_root(project: dict[str, Any]) -> Path:
+    root = project.get("_project_root")
+    if not root:
+        raise ToolingError(
+            "Project root was not resolved by the canonical project loader",
+            "frontmattering_project/v0_3",
+            "Authoring commands require the same closed project model as corpus selection.",
+            "Load the project through frontmattering.corpus_selection.load_project.",
+            error_id="FRONTMATTERING-AUTHORING-PROJECT-ROOT-MISSING",
+        )
+    return Path(str(root))
+
+
+def _project_paths(project: dict[str, Any]) -> list[Path]:
+    root = _project_root(project)
+    selection = project.get("_selection") or {}
+    include = selection.get("include") or []
+    exclude = selection.get("exclude") or []
+    selected: set[Path] = set()
+    for pattern in include:
+        for candidate in root.glob(str(pattern)):
+            if candidate.is_file() and candidate.suffix.lower() == ".md":
+                selected.add(candidate.resolve())
+    for pattern in exclude:
+        for candidate in root.glob(str(pattern)):
+            selected.discard(candidate.resolve())
+    return sorted(selected, key=lambda item: item.as_posix())
+
+
+def _parse_existing_frontmatter(path: Path) -> dict[str, Any] | None:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ToolingError(
+            "Existing Markdown cannot be read during authoring",
+            str(path),
+            "Router discovery and catalog harvesting must not silently skip unreadable selected documents.",
+            "Repair filesystem permissions or remove the unreadable path from the project corpus.",
+            {"error": str(exc)},
+            error_id="FRONTMATTERING-AUTHORING-READ-FAILED",
+        ) from exc
+    if not text.startswith("---"):
+        return None
+    fm, _body, findings = parse_frontmatter(text)
+    if findings:
+        raise ToolingError(
+            "Selected governed Markdown has invalid frontmatter",
+            str(path),
+            "Router discovery and catalog harvesting refuse to hide malformed governed documents.",
+            "Validate and repair the selected document before running authoring promotion.",
+            {"finding_count": len(findings), "finding_ids": [getattr(f, "id", None) if hasattr(f, "id") else str(f[0]) for f in findings]},
+            error_id="FRONTMATTERING-AUTHORING-GOVERNED-DOC-INVALID",
+        )
+    if fm is None:
+        raise ToolingError(
+            "Existing Markdown frontmatter parse returned no document and no finding",
+            str(path),
+            "This is an internal authoring invariant violation.",
+            "Report the kernel bug with the path and input bytes.",
+            error_id="FRONTMATTERING-AUTHORING-PARSE-INVARIANT",
+        )
+    return fm if isinstance(fm, dict) else None
+
+
+def _router_records(project: dict[str, Any]) -> list[tuple[Path, dict[str, Any]]]:
+    records: list[tuple[Path, dict[str, Any]]] = []
+    for path in _project_paths(project):
+        fm = _parse_existing_frontmatter(path)
+        if not isinstance(fm, dict):
+            continue
+        adc = fm.get("ai_document_contract", {}) if isinstance(fm, dict) else {}
+        if adc.get("document_role") == "package_router":
+            records.append((path, fm))
+    return records
+
+
+def _canonical_owner_document_id(project: dict[str, Any]) -> str:
+    routers = _router_records(project)
+    if len(routers) != 1:
+        raise ToolingError(
+            "Frontmattering project must have exactly one package_router for starter ownership",
+            ", ".join(path.as_posix() for path, _fm in routers) or "none",
+            "New and promoted non-router documents need one canonical owner document id.",
+            "Initialize the project or promote exactly one router before adding guide/spec documents.",
+            {"router_count": len(routers)},
+            error_id="FRONTMATTERING-AUTHORING-ROUTER-COUNT-INVALID",
+        )
+    adc = routers[0][1].get("ai_document_contract", {})
+    did = adc.get("document_id")
+    if not isinstance(did, str) or not did:
+        raise ToolingError(
+            "The package_router has no document_id",
+            routers[0][0].as_posix(),
+            "Ownership binding requires a stable owner document id.",
+            "Repair the router frontmatter.",
+            error_id="FRONTMATTERING-AUTHORING-ROUTER-ID-MISSING",
+        )
+    return did
+
+
+def _all_declared_task_tags(project: dict[str, Any], extra_frontmatters: Iterable[dict[str, Any]] = ()) -> list[str]:
+    tags: set[str] = set()
+    default_tag = project.get("default_task_tag")
+    if isinstance(default_tag, str) and default_tag:
+        tags.add(default_tag)
+    for _path in _project_paths(project):
+        fm = _parse_existing_frontmatter(_path)
+        if not isinstance(fm, dict):
+            continue
+        routing = fm.get("routing", {}) if isinstance(fm, dict) else {}
+        for field in ("read_when_tags", "skip_when_tags", "task_catalog"):
+            for tag in routing.get(field) or []:
+                if isinstance(tag, str) and tag and tag not in BUILTIN_SKIP_TAGS:
+                    tags.add(tag)
+    for fm in extra_frontmatters:
+        routing = fm.get("routing", {}) if isinstance(fm, dict) else {}
+        for field in ("read_when_tags", "skip_when_tags", "task_catalog"):
+            for tag in routing.get(field) or []:
+                if isinstance(tag, str) and tag and tag not in BUILTIN_SKIP_TAGS:
+                    tags.add(tag)
+    return sorted(tags)
+
+
+def _write_frontmatter(path: Path, fm: dict[str, Any], body: str) -> None:
+    y = yaml.safe_dump(fm, sort_keys=False, allow_unicode=True, width=1000).rstrip()
+    path.write_text(f"---\n{y}\n---\n{body}", encoding="utf-8")
+
+
+def _split_existing_doc(path: Path) -> tuple[dict[str, Any], str]:
+    text = path.read_text(encoding="utf-8")
+    fm, body, findings = parse_frontmatter(text)
+    if fm is None or findings:
+        raise ToolingError(
+            "Selected Markdown is not a valid Frontmattering document",
+            str(path),
+            "Catalog harvesting mutates only valid governed frontmatter and refuses guessed repairs.",
+            "Validate the document first, then rerun the promotion command.",
+            {"finding_count": len(findings)},
+            error_id="FRONTMATTERING-AUTHORING-GOVERNED-DOC-INVALID",
+        )
+    return fm, body
+
+
+def refresh_router_task_catalog(project: dict[str, Any], *, extra_frontmatters: Iterable[dict[str, Any]] = ()) -> list[Path]:
+    """Refresh exactly one router's task_catalog from current promoted tags."""
+    routers = _router_records(project)
+    if len(routers) != 1:
+        raise ToolingError(
+            "Cannot refresh task catalog without exactly one package_router",
+            ", ".join(path.as_posix() for path, _fm in routers) or "none",
+            "A corpus-local task catalog must have one router owner.",
+            "Promote or repair the router so exactly one package_router is selected.",
+            {"router_count": len(routers)},
+            error_id="FRONTMATTERING-AUTHORING-CATALOG-ROUTER-COUNT-INVALID",
+        )
+    router_path, _router_fm = routers[0]
+    fm, body = _split_existing_doc(router_path)
+    routing = fm.setdefault("routing", {})
+    catalog = _all_declared_task_tags(project, extra_frontmatters=extra_frontmatters)
+    if routing.get("task_catalog") == catalog:
+        return []
+    routing["task_catalog"] = catalog
+    _write_frontmatter(router_path, fm, body)
+    return [router_path]
+
+
+def _remove_generated_starter_router(project: dict[str, Any], *, replacement_path: Path) -> list[Path]:
+    sid = str(project["document_set_id"])
+    starter_id = f"{sid}-START-HERE"
+    removed: list[Path] = []
+    for path, fm in list(_router_records(project)):
+        if path.resolve() == replacement_path.resolve():
+            continue
+        adc = fm.get("ai_document_contract", {})
+        di = fm.get("deepest_intention", {})
+        if adc.get("document_id") == starter_id and di.get("canonical_owner_document_id") == starter_id:
+            path.unlink()
+            removed.append(path)
+    return removed
+
+
+def dump_doc(frontmatter: dict[str, Any], title: str, sections: list[str]) -> str:
+    y = yaml.safe_dump(frontmatter, sort_keys=False, allow_unicode=True, width=1000).rstrip()
+    body = [f"# {title}", ""]
+    for s in sections:
+        body += [f"## {s}", "", "TODO", ""]
+    return f"---\n{y}\n---\n\n" + "\n".join(body).rstrip() + "\n"
+
+
+def init_project(root: Path, set_id: str, title: str, force: bool = False) -> list[Path]:
+    root.mkdir(parents=True, exist_ok=True)
+    cfg_dir = root / ".frontmattering"; cfg_dir.mkdir(exist_ok=True)
+    cfg = cfg_dir / "project.yaml"
+    docs = root / "docs"; docs.mkdir(exist_ok=True)
+    router = docs / "00_START_HERE.md"
+    for p in (cfg, router):
+        if p.exists() and not force:
+            raise ToolingError("Generated file already exists", str(p), "Authoring scaffolds do not overwrite files by default.", "Choose another path or use --force intentionally.", error_id="FRONTMATTERING-AUTHORING-OVERWRITE-BLOCKED")
+    sid = slug(set_id)
+    cfg.write_text(yaml.safe_dump({
+        "project_schema": PROJECT_SCHEMA,
+        "document_set_id": sid,
+        "document_set_version": "0.1.0",
+        "title": title,
+        "default_task_tag": "general",
+        "next_load_order": 20,
+        "validation_profile": "default",
+        "corpus": {"include": ["docs/**/*.md"], "exclude": []},
+    }, sort_keys=False), encoding="utf-8")
+    fm = {
+      "ai_document_contract": {"schema_version": SCHEMA_VERSION, "document_id": f"{sid}-START-HERE", "document_title": f"{title} — start here", "document_version": "0.1.0", "document_set_id": sid, "document_set_version": "0.1.0", "document_role": "package_router", "document_kind": "orientation", "authority": "orientation_only", "lifecycle_state": "draft", "primary_action_expected": "Orient before substantive work on this document set.", "must_not_be_used_for": ["Treating orientation as normative authority."], "audience": {"primary": "dual", "human_reader_role": "maintainer", "human_readability_priority": "high"}, "body_binding": {"clause_index_required": False, "body_required_sections": ["Purpose", "How to use", "Claim boundary"]}},
+      "template_contract": {"schema_version": TEMPLATE_SCHEMA, "template_id": "orientation_router/default", "conformance_required": True},
+      "routing": {"load_order": 1, "agent_summary": f"Entry point for {title}.", "task_catalog": ["general"], "read_when": ["Beginning substantive work on this document set."], "read_when_tags": ["general"], "skip_when": ["The task is unrelated to this document set."], "skip_when_tags": ["unrelated_document_set"]},
+      "deepest_intention": {"intention_id": f"{sid}-DI-ORIENT", "canonical_owner_document_id": f"{sid}-START-HERE", "ownership": "owns", "one_sentence": "Provide bounded orientation before readers spend context on document bodies.", "protected_value": "Readers can identify authority, order, and hazards without reconstructing them from prose.", "failure_mode_prevented": ["Readers infer authority from filenames or prose alone."], "common_wrong_interpretations": ["The router is normative authority."], "achieved_by": ["A validated brief and typed document mesh."], "not_achieved_by": ["Treating a clean validation result as semantic approval."], "validator_gates": ["FRONTMATTERING-KERNEL-VALIDATE"], "evidence_required": ["The document set validates with the pinned kernel."], "not_the_intention": [{"statement": "The router approves the document set.", "category": "authority_laundering", "confusion_tether": "Orientation identifies structure; it does not approve content.", "aliases": ["orientation is approval"]}]},
+      "claim_boundary_packet": {"claimed_state": "AUTHORED_DRAFT", "verifies": ["This document declares the entry point and routing intent."], "does_not_verify": ["Semantic adequacy or release readiness of the document set."], "judgment_left_to_agent": ["Whether the documents are fit for the current purpose."]},
+      "relationships": [], "evidence_references": []}
+    router.write_text(dump_doc(fm, f"{title} — start here", ["Purpose", "How to use", "Claim boundary"]), encoding="utf-8")
+    return [cfg, router]
+
+
+def starter_frontmatter(path: Path, profile: str, title: str, summary: str | None = None) -> tuple[dict[str, Any], list[str]]:
+    """Build the canonical starter profile frontmatter without writing a file."""
+    if profile not in PROFILES:
+        raise ToolingError("Unknown authoring profile", profile, "The profile is outside the shipped closed starter profile set.", f"Choose one of: {', '.join(sorted(PROFILES))}.", error_id="FRONTMATTERING-AUTHORING-PROFILE-UNKNOWN")
+    project = load_project(path.parent)
+    sid = project["document_set_id"]; dsv = project.get("document_set_version", "0.1.0")
+    did = f"{sid}-{slug(path.stem)}"
+    kind, role, authority, claim, template = PROFILES[profile]
+    task = project.get("default_task_tag", "general")
+    load_order = 1 if profile == "router" else int(project.get("next_load_order", 20))
+    sections = ["Purpose", "How to use", "Claim boundary"] if profile == "router" else ["Purpose", "Content", "Claim boundary"]
+    owner_id = did if profile == "router" else _canonical_owner_document_id(project)
+    if profile == "router":
+        intention = {"intention_id": f"{sid}-DI-ORIENT", "ownership": "owns", "canonical_owner_document_id": did, "one_sentence": "Provide bounded orientation before readers spend context on document bodies.", "protected_value": "Readers can identify authority, order, and hazards without reconstructing them from prose.", "failure_mode_prevented": ["Readers infer authority from filenames or prose alone."], "common_wrong_interpretations": ["The router is normative authority."], "achieved_by": ["A validated brief and typed document mesh."], "not_achieved_by": ["Treating a clean validation result as semantic approval."], "validator_gates": ["FRONTMATTERING-KERNEL-VALIDATE"], "evidence_required": ["The document set validates with the pinned kernel."], "not_the_intention": [{"statement": "The router approves the document set.", "category": "authority_laundering", "confusion_tether": "Orientation identifies structure; it does not approve content.", "aliases": ["orientation is approval"]}]}
+        primary_action = "Orient before substantive work on this document set."
+        must_not = ["Treating orientation as normative authority."]
+        read_when = ["Beginning substantive work on this document set."]
+        catalog = _all_declared_task_tags(project, extra_frontmatters=()) or [str(task)]
+    else:
+        intention = {"intention_id": f"{sid}-DI-ORIENT", "ownership": "binds_to", "canonical_owner_document_id": owner_id}
+        primary_action = f"Use this document for its declared {profile} purpose."
+        must_not = ["Claims beyond the declared claim boundary."]
+        read_when = [f"The task requires this {profile}."]
+        catalog = None
+    routing = {"agent_summary": summary or title, "read_when": read_when, "read_when_tags": [task], "skip_when": ["The task does not require this document."], "skip_when_tags": ["unrelated_document_set"], "load_order": load_order}
+    if catalog is not None:
+        routing["task_catalog"] = catalog
+    fm = {
+      "ai_document_contract": {"schema_version": SCHEMA_VERSION, "document_id": did, "document_set_id": sid, "document_version": "0.1.0", "document_set_version": dsv, "document_title": title, "document_kind": kind, "document_role": role, "lifecycle_state": "draft" if claim=="AUTHORED_DRAFT" else "candidate", "audience": {"primary": "dual", "human_reader_role": "maintainer", "human_readability_priority": "high"}, "authority": authority, "primary_action_expected": primary_action, "body_binding": {"body_required_sections": sections, "clause_index_required": False}, "clause_prefixes": [slug(sid)[:12]], "must_not_be_used_for": must_not},
+      "routing": routing,
+      "deepest_intention": intention,
+      "claim_boundary_packet": {"claimed_state": claim, "verifies": [f"This document records authored {profile} content."], "does_not_verify": ["Independent correctness, adoption, or release readiness."], "judgment_left_to_agent": ["Whether the body is semantically adequate for the task."]},
+      "relationships": [], "evidence_references": [],
+      "template_contract": {"schema_version": TEMPLATE_SCHEMA, "template_id": template, "conformance_required": profile == "router"}}
+    return fm, sections
+
+
+def new_document(path: Path, profile: str, title: str, summary: str | None = None, force: bool = False) -> Path:
+    if path.exists() and not force:
+        raise ToolingError("Generated file already exists", str(path), "Authoring scaffolds do not overwrite files by default.", "Choose another path or use --force intentionally.", error_id="FRONTMATTERING-AUTHORING-OVERWRITE-BLOCKED")
+    fm, sections = starter_frontmatter(path, profile, title, summary=summary)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(dump_doc(fm, title, sections), encoding="utf-8")
+    if profile != "router":
+        refresh_router_task_catalog(load_project(path.parent), extra_frontmatters=[fm])
+    return path

frontmattering/body_tether.py

@@ -0,0 +1,176 @@
+"""Body/frontmatter freshness tether utilities for Frontmattering frontmatter."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any, Sequence
+
+import yaml
+
+from .core import Y12Core, split_frontmatter
+from .harness_errors import ToolingError
+
+BODY_TETHER_SCHEMA_VERSION = "frontmattering_body_tether/v1"
+BODY_TETHER_ALGORITHM = "sha256"
+BODY_TETHER_CANONICALIZATION = "frontmattering_markdown_body_bytes_v1"
+_FM_BYTES_RE = re.compile(rb"\A---(?:\n|\r\n).*?(?:\n|\r\n)---(?:\n|\r\n|$)", re.DOTALL)
+_SHA256_RE = re.compile(r"[0-9a-f]{64}")
+
+
+def canonical_body_bytes(raw: bytes) -> bytes:
+    """frontmattering_markdown_body_bytes_v1: raw Markdown bytes minus first frontmatter block."""
+    return _FM_BYTES_RE.sub(b"", raw, count=1)
+
+
+def body_sha256_for_bytes(raw: bytes) -> str:
+    return hashlib.sha256(canonical_body_bytes(raw)).hexdigest()
+
+
+def _canonical_fields(canonical_fields: Sequence[str]) -> list[str]:
+    if not isinstance(canonical_fields, Sequence) or isinstance(canonical_fields, (str, bytes)):
+        raise ToolingError(
+            "Body tether canonical field set is unavailable",
+            "body_tether_canonical_trust_fields",
+            "The validator was invoked without the spec-declared canonical trust-field list.",
+            "Restore the body_tether_canonical_trust_fields machine block in the Frontmattering spec.",
+            error_id="FRONTMATTERING-BODY-TETHER-CANONICAL-FIELDS-MISSING",
+        )
+    fields = [str(item) for item in canonical_fields]
+    if not fields or any(not item.strip() for item in fields) or len(set(fields)) != len(fields):
+        raise ToolingError(
+            "Body tether canonical field set is invalid",
+            "body_tether_canonical_trust_fields",
+            "The spec-declared canonical trust-field list must be non-empty and duplicate-free.",
+            "Repair the body_tether_canonical_trust_fields machine block in the Frontmattering spec.",
+            {"canonical_fields": fields},
+            error_id="FRONTMATTERING-BODY-TETHER-CANONICAL-FIELDS-INVALID",
+        )
+    return fields
+
+
+def _dig(fm: dict[str, Any], dotted: str) -> Any:
+    cur: Any = fm
+    for part in dotted.split("."):
+        if isinstance(cur, dict) and part in cur:
+            cur = cur[part]
+        else:
+            return None
+    return cur
+
+
+def tethered_fields_sha256(fm: dict[str, Any], canonical_fields: Sequence[str]) -> str:
+    """Digest the complete spec-declared canonical trust-bearing field set."""
+    fields = _canonical_fields(canonical_fields)
+    payload = [[path, _dig(fm, path)] for path in fields]
+    blob = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(blob).hexdigest()
+
+
+def classify_tether(raw: bytes, fm: dict[str, Any], canonical_fields: Sequence[str]) -> dict[str, Any]:
+    """Return FRESH/STALE/UNTETHERED status under canonical-scope semantics."""
+    fields = _canonical_fields(canonical_fields)
+    tether = fm.get("body_tether") if isinstance(fm, dict) else None
+    if tether is None:
+        return {"freshness": "UNTETHERED", "summary_trust": "orientation_only", "reasons": ["body_tether absent"], "body_sha256_current": body_sha256_for_bytes(raw), "canonical_tethered_fields": fields}
+    if not isinstance(tether, dict):
+        return {"freshness": "STALE", "summary_trust": "do_not_rely_without_reading_body", "reasons": ["body_tether malformed"], "body_sha256_current": body_sha256_for_bytes(raw), "canonical_tethered_fields": fields}
+    current_body_sha = body_sha256_for_bytes(raw)
+    current_fields_sha = tethered_fields_sha256(fm, fields)
+    reasons: list[str] = []
+    if "tethered_fields" in tether:
+        reasons.append("body_tether.tethered_fields forbidden")
+    if tether.get("schema_version") != BODY_TETHER_SCHEMA_VERSION:
+        reasons.append("schema_version mismatch")
+    if tether.get("body_algorithm") != BODY_TETHER_ALGORITHM:
+        reasons.append("body_algorithm mismatch")
+    if tether.get("body_canonicalization") != BODY_TETHER_CANONICALIZATION:
+        reasons.append("body_canonicalization unknown")
+    if tether.get("body_sha256") != current_body_sha:
+        reasons.append("body_sha256 mismatch")
+    if tether.get("tethered_fields_sha256") != current_fields_sha:
+        reasons.append("tethered_fields_sha256 mismatch")
+    return {
+        "freshness": "FRESH" if not reasons else "STALE",
+        "summary_trust": "fresh_canonical_tether_declared" if not reasons else "do_not_rely_without_reading_body",
+        "reasons": reasons,
+        "body_sha256_current": current_body_sha,
+        "body_sha256_declared": tether.get("body_sha256"),
+        "tethered_fields_sha256_current": current_fields_sha,
+        "tethered_fields_sha256_declared": tether.get("tethered_fields_sha256"),
+        "canonical_tethered_fields": fields,
+    }
+
+
+def _sha256_like(value: Any) -> bool:
+    return isinstance(value, str) and _SHA256_RE.fullmatch(value) is not None
+
+
+def findings_for_tether(raw: bytes, fm: dict[str, Any], canonical_fields: Sequence[str]) -> list[tuple[str, str]]:
+    _canonical_fields(canonical_fields)
+    tether = fm.get("body_tether") if isinstance(fm, dict) else None
+    if tether is None:
+        return []
+    if not isinstance(tether, dict):
+        return [("FRONTMATTERING-FM-BODY-TETHER-MALFORMED", "body_tether")]
+    out: list[tuple[str, str]] = []
+    required = ["schema_version", "body_algorithm", "body_canonicalization", "body_sha256", "tethered_fields_sha256"]
+    missing = [name for name in required if name not in tether]
+    if missing:
+        out.append(("FRONTMATTERING-FM-BODY-TETHER-MALFORMED", ",".join(missing)))
+        return out
+    if "tethered_fields" in tether:
+        out.append(("FRONTMATTERING-FM-BODY-TETHER-MALFORMED", "body_tether.tethered_fields"))
+    if tether.get("schema_version") != BODY_TETHER_SCHEMA_VERSION:
+        out.append(("FRONTMATTERING-FM-BODY-TETHER-MALFORMED", "body_tether.schema_version"))
+    if tether.get("body_algorithm") != BODY_TETHER_ALGORITHM:
+        out.append(("FRONTMATTERING-FM-BODY-TETHER-MALFORMED", "body_tether.body_algorithm"))
+    if tether.get("body_canonicalization") != BODY_TETHER_CANONICALIZATION:
+        out.append(("FRONTMATTERING-FM-BODY-TETHER-UNKNOWN-CANONICALIZATION", "body_tether.body_canonicalization"))
+    if not _sha256_like(tether.get("body_sha256")):
+        out.append(("FRONTMATTERING-FM-BODY-TETHER-MALFORMED", "body_tether.body_sha256"))
+    elif tether.get("body_sha256") != body_sha256_for_bytes(raw):
+        out.append(("FRONTMATTERING-FM-BODY-DIGEST-MISMATCH", "body_tether.body_sha256"))
+    if not _sha256_like(tether.get("tethered_fields_sha256")):
+        out.append(("FRONTMATTERING-FM-BODY-TETHER-MALFORMED", "body_tether.tethered_fields_sha256"))
+    elif tether.get("tethered_fields_sha256") != tethered_fields_sha256(fm, canonical_fields):
+        out.append(("FRONTMATTERING-FM-TETHERED-FIELDS-MISMATCH", "body_tether.tethered_fields_sha256"))
+    return out
+
+
+def read_frontmatter_and_body(path: Path) -> tuple[dict[str, Any], str]:
+    text = path.read_text(encoding="utf-8")
+    fm_text, body, findings = split_frontmatter(text)
+    if findings or fm_text is None:
+        raise ToolingError("Body tether update cannot parse frontmatter", str(path), "The file does not contain parseable Frontmattering frontmatter.", "Add a valid byte-zero Frontmattering YAML frontmatter block before updating the tether.")
+    fm = yaml.load(fm_text, Loader=Y12Core)
+    if not isinstance(fm, dict):
+        raise ToolingError("Body tether update cannot parse frontmatter", str(path), "The frontmatter root is not a mapping.", "Rewrite the frontmatter as a YAML mapping before updating the tether.")
+    return fm, body
+
+
+def write_frontmatter_and_body(path: Path, fm: dict[str, Any], body: str) -> None:
+    rendered = yaml.safe_dump(fm, sort_keys=False, allow_unicode=True, width=1000).rstrip()
+    path.write_text(f"---\n{rendered}\n---\n{body}", encoding="utf-8")
+
+
+def update_tether(path: Path, *, add: bool = False, canonical_fields: Sequence[str]) -> bool:
+    """Refresh body_tether for one file. Return True when a block was written."""
+    fields = _canonical_fields(canonical_fields)
+    fm, body = read_frontmatter_and_body(path)
+    if "body_tether" not in fm and not add:
+        return False
+    fm["body_tether"] = {
+        "schema_version": BODY_TETHER_SCHEMA_VERSION,
+        "body_algorithm": BODY_TETHER_ALGORITHM,
+        "body_canonicalization": BODY_TETHER_CANONICALIZATION,
+        "body_sha256": "0" * 64,
+        "tethered_fields_sha256": "0" * 64,
+    }
+    write_frontmatter_and_body(path, fm, body)
+    fm, body = read_frontmatter_and_body(path)
+    fm["body_tether"]["body_sha256"] = body_sha256_for_bytes(path.read_bytes())
+    fm["body_tether"]["tethered_fields_sha256"] = tethered_fields_sha256(fm, fields)
+    write_frontmatter_and_body(path, fm, body)
+    return True

frontmattering/common/__init__.py

@@ -0,0 +1,3 @@
+"""Structured errors used by Frontmattering."""
+from .errors import (FrontmatteringError, ParsingError, ValidationError, SchemaValidationError, ReentrancyError, CollectorTimeoutError)
+__all__ = ["FrontmatteringError", "ParsingError", "ValidationError", "SchemaValidationError", "ReentrancyError", "CollectorTimeoutError"]