secondbrain-py 0.2.1__py3-none-any.whl

brain/wiki/edit_classifier.py

@@ -0,0 +1,215 @@
+"""Edit classifier: classify a vault file edit as trivial or non-trivial.
+
+A **trivial** edit is one whose canonical structural fingerprint did NOT
+change — only body prose / whitespace / HTML comments / ignored frontmatter
+fields were touched.  A **non-trivial** edit requires a full Quartz build
+(fingerprint changed, slug unknown, manifest missing / unreadable, source
+path diverged from manifest record, etc.).
+
+Used by the watcher (T6) to route edits through the fast path or the full
+build path.
+
+Public surface:
+    classify_edit(*, fastpath_dir, source_path, vault_root) → ClassificationResult
+
+Slug helpers live in ``brain.wiki.slug``; import them from there.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from brain.wiki.fastpath_manifest import (
+    ManifestError,
+    compute_fingerprint,
+    read_manifest,
+)
+from brain.wiki.slug import slugify_source_path
+
+# ---------------------------------------------------------------------------
+# Public types
+# ---------------------------------------------------------------------------
+
+
+class EditClassification(Enum):
+    """Result of classify_edit."""
+
+    TRIVIAL = "trivial"
+    NON_TRIVIAL = "non-trivial"
+
+
+@dataclass(frozen=True, slots=True)
+class ClassificationResult:
+    """Full result of a single-file edit classification."""
+
+    classification: EditClassification
+    reason: str  # human-readable, for logs / telemetry
+    slug: str | None  # None only if slug could not be determined
+    old_fingerprint: str | None  # None if manifest missing / slug unknown
+    new_fingerprint: str | None  # None if file unreadable / compute failed
+
+
+# ---------------------------------------------------------------------------
+# Public classifier
+# ---------------------------------------------------------------------------
+
+
+def classify_edit(
+    *,
+    fastpath_dir: Path,
+    source_path: Path,
+    vault_root: Path,
+) -> ClassificationResult:
+    """Classify a single vault file edit as trivial or non-trivial.
+
+    A trivial edit is one where the canonical structural fingerprint is
+    unchanged — only prose / whitespace / ignored frontmatter fields were
+    modified.  A non-trivial edit (or any error condition) falls back to a
+    full Quartz build.
+
+    Algorithm:
+      1. Validate ``source_path`` is inside ``vault_root`` (raises ValueError
+         on programmer error — T6 must pre-validate event paths).
+      2. Compute slug from ``source_path`` relative to ``vault_root``.
+      3. Check ``source_path`` still exists (delete/move → non-trivial).
+      4. Read manifest from ``fastpath_dir``; catch ManifestError → non-trivial.
+      5. Look up slug in manifest; missing → non-trivial.
+      5a. **Rename guard:** compare current vault-relative path against
+          ``entry.source_path`` from the manifest.  If they differ, the slug
+          collision is spurious (e.g. "a b.md" and "a-b.md" both slugify to
+          ``a-b``); force non-trivial so the full build reconciles the rename.
+      6. Read file bytes; OS error → non-trivial.
+      7. After step 5a verifies the current vault-relative path equals
+         ``entry.source_path``, compute the new fingerprint using the manifest's
+         recorded ``source_path`` / ``output_path`` (sanity guard against
+         drift between the manifest writer's and reader's path conventions).
+      8. Compare fingerprints; equal → trivial, unequal → non-trivial.
+
+    Args:
+        fastpath_dir: Path to ``<vault>/.quartz/.cache/fastpath/``.
+        source_path: Absolute path to the edited file.
+        vault_root: Absolute path to the vault root directory.
+
+    Returns:
+        :class:`ClassificationResult` with all fields populated.
+
+    Raises:
+        ValueError: If ``source_path`` is not inside ``vault_root``.
+    """
+    # Step 1 — validate source_path inside vault_root (programmer-error guard).
+    try:
+        source_path.relative_to(vault_root)
+    except ValueError as exc:
+        raise ValueError(
+            f"source_path {source_path!r} is not inside vault_root {vault_root!r}"
+        ) from exc
+
+    # Step 2 — compute slug.
+    slug = slugify_source_path(source_path, vault_root)
+
+    # Step 3 — source file must exist (delete / move → non-trivial).
+    if not source_path.exists():
+        return ClassificationResult(
+            classification=EditClassification.NON_TRIVIAL,
+            reason="source file missing",
+            slug=slug,
+            old_fingerprint=None,
+            new_fingerprint=None,
+        )
+
+    # Step 4 — read manifest; any ManifestError → non-trivial.
+    try:
+        manifest = read_manifest(fastpath_dir)
+    except ManifestError as exc:
+        raw = str(exc)
+        # Produce a user-friendly reason while preserving the error detail.
+        if "cannot read manifest" in raw:
+            reason = "manifest missing — first build pending or cleared"
+        elif "malformed manifest JSON" in raw:
+            reason = f"manifest unreadable: {exc}"
+        elif "version" in raw:
+            reason = raw  # already contains version numbers from read_manifest
+        else:
+            reason = f"manifest error: {exc}"
+        return ClassificationResult(
+            classification=EditClassification.NON_TRIVIAL,
+            reason=reason,
+            slug=slug,
+            old_fingerprint=None,
+            new_fingerprint=None,
+        )
+
+    # Step 5 — look up slug entry.
+    entry = manifest.slugs.get(slug)
+    if entry is None:
+        return ClassificationResult(
+            classification=EditClassification.NON_TRIVIAL,
+            reason=f"slug not in manifest: {slug}",
+            slug=slug,
+            old_fingerprint=None,
+            new_fingerprint=None,
+        )
+
+    # Step 5a — rename guard: verify current path matches manifest's record.
+    # Two distinct filenames can produce the same slug (e.g. "a b.md" and
+    # "a-b.md" both → "a-b").  If the paths differ the slug match is spurious;
+    # force full build so the rename is properly handled.
+    current_source_path = source_path.relative_to(vault_root).as_posix()
+    if entry.source_path != current_source_path:
+        return ClassificationResult(
+            classification=EditClassification.NON_TRIVIAL,
+            reason=(
+                f"source path changed: manifest={entry.source_path!r} "
+                f"current={current_source_path!r}"
+            ),
+            slug=slug,
+            old_fingerprint=entry.fingerprint,
+            new_fingerprint=None,
+        )
+
+    # Step 6 — read current file bytes.
+    try:
+        source_bytes = source_path.read_bytes()
+    except OSError as exc:
+        return ClassificationResult(
+            classification=EditClassification.NON_TRIVIAL,
+            reason=f"source unreadable: {exc}",
+            slug=slug,
+            old_fingerprint=entry.fingerprint,
+            new_fingerprint=None,
+        )
+
+    # Step 7 — compute new fingerprint using manifest's recorded paths.
+    try:
+        new_fp = compute_fingerprint(
+            source_bytes=source_bytes,
+            slug=slug,
+            source_path=entry.source_path,
+            output_path=entry.output_path,
+        )
+    except ManifestError as exc:
+        return ClassificationResult(
+            classification=EditClassification.NON_TRIVIAL,
+            reason=f"fingerprint computation failed: {exc}",
+            slug=slug,
+            old_fingerprint=entry.fingerprint,
+            new_fingerprint=None,
+        )
+
+    # Step 8 — compare fingerprints.
+    if new_fp == entry.fingerprint:
+        return ClassificationResult(
+            classification=EditClassification.TRIVIAL,
+            reason="fingerprint unchanged",
+            slug=slug,
+            old_fingerprint=entry.fingerprint,
+            new_fingerprint=new_fp,
+        )
+    return ClassificationResult(
+        classification=EditClassification.NON_TRIVIAL,
+        reason="fingerprint changed",
+        slug=slug,
+        old_fingerprint=entry.fingerprint,
+        new_fingerprint=new_fp,
+    )

brain/wiki/errors.py

@@ -0,0 +1,10 @@
+"""Wiki-pipeline exceptions."""
+from brain.errors import BrainError
+
+
+class BrainWikiError(BrainError):
+    """Base class for wiki-pipeline failures (build, swap, watch)."""
+
+
+class BrainWikiBuildError(BrainWikiError):
+    """The Quartz build subprocess exited non-zero, timed out, or the workspace is broken."""

brain/wiki/fastpath_manifest.py

@@ -0,0 +1,475 @@
+"""Fast-path manifest: per-slug structural fingerprint + manifest I/O.
+
+Python counterpart to ``brain/quartz_overrides/quartz/util/fastpath_manifest.ts``.
+Both implementations MUST produce byte-identical canonical blobs for the same
+input — verified by ``tests/wiki/test_fastpath_fingerprint_parity.py``.
+
+Canonical-blob format: ``docs/specs/2026-05-09-fastpath-fingerprint.md``.
+
+Design constraints:
+- Pure Python; no Node/subprocess.
+- Reads manifest.json written by the TS full-build hook.
+- Computes fingerprint at classifier time (T3) for the current file on disk.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import struct
+from dataclasses import dataclass
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from brain.errors import BrainError
+from brain.vault.frontmatter import parse_frontmatter
+
+from ._github_slugger import Slugger
+
+FINGERPRINT_VERSION: int = 1
+
+# ---------------------------------------------------------------------------
+# Structural frontmatter fields — canonical key order (spec §Frontmatter blob).
+# Changes to this list must bump FINGERPRINT_VERSION.
+# ---------------------------------------------------------------------------
+
+_STRUCTURAL_FIELD_ORDER: tuple[str, ...] = (
+    "title", "draft", "publish", "tags", "aliases", "permalink", "slug",
+    "lang", "cssclasses", "socialImage", "enableToc", "comments", "kind",
+    "description", "socialDescription", "date", "created", "modified",
+    "updated", "published",
+)
+
+_STRUCTURAL_FIELDS: frozenset[str] = frozenset(_STRUCTURAL_FIELD_ORDER)
+
+# Array fields: JSON value is a sorted string array (or null if absent).
+_ARRAY_FIELDS: frozenset[str] = frozenset(("tags", "aliases", "cssclasses"))
+
+# Boolean fields: JSON value is bool (or null if absent).
+_BOOL_FIELDS: frozenset[str] = frozenset(("draft", "publish", "enableToc", "comments"))
+
+# Date fields: JSON value is iso8601 string (or null if absent).
+_DATE_FIELDS: frozenset[str] = frozenset(
+    ("date", "created", "modified", "updated", "published")
+)
+
+# ---------------------------------------------------------------------------
+# Ignored frontmatter fields (Appendix A) — changes do NOT affect rendering.
+# Changes to this list must bump FINGERPRINT_VERSION.
+# ---------------------------------------------------------------------------
+
+_IGNORED_FIELDS: frozenset[str] = frozenset({
+    # Identity / dedup metadata
+    "id", "external_id", "content_type", "source", "source_path",
+    "source_template_id", "source_template_name", "vault_path", "canonical", "hash",
+    # Ingest provenance
+    "ai_assisted", "autogenerated", "last_reviewed", "collected_by", "owner",
+    "organization_id", "organization_name",
+    # Brain workflow tracking
+    "autopilot_deferred_actions", "autopilot_digest", "autopilot_inventory",
+    "autopilot_subscription_renewal", "autopilot_sweep_compliance",
+    "autopilot_sweep_equipment", "autopilot_sweep_escalation",
+    "autopilot_sweep_payments", "autopilot_sweep_payroll",
+    "autopilot_sweep_proposals", "autopilot_sweep_routes",
+    "autopilot_sweep_seasonal", "autopilot_sweep_timesheets",
+    "autopilot_sweep_workload",
+    "billcom", "billcom_auto_sync", "check_grace_period", "hits",
+    "hours_saved_by_workflow", "hours_saved_today", "hours_saved_totals",
+    "komply_iq_sweep_deficiency", "komply_iq_sweep_invoice_delivery",
+    "komply_iq_sweep_invoice_generation", "komply_iq_sweep_payment_reminders",
+    "komply_iq_sweep_proposal_conversion", "komply_iq_sweep_quality_assurance",
+    "komply_iq_sweep_regulatory_filing",
+    "mandate", "proposal_expiration", "proposal_follow_up_reminders",
+    "quota", "report_usage", "reset_ai_quotas", "sidebar_position", "status",
+    "trial_expiration_check",
+    # Krisp/Slack/Gmail metadata
+    "participants", "duration_min", "thread_id", "channel", "attendees",
+    "to", "from", "subject", "schedule",
+    # Free-form metadata not rendered
+    "context", "keywords", "notes", "predecessor", "principle", "purview",
+    "render", "seo", "sweep", "where", "with", "wrote",
+})
+
+# ---------------------------------------------------------------------------
+# Regex patterns for body parsing
+# ---------------------------------------------------------------------------
+
+# Non-transclusion wikilinks: [[target]] or [[target|alias]].
+# Negative lookbehind for ! excludes transclusions.
+# Group 1 = raw target text (including #anchor if present).
+_WIKILINK_RE: re.Pattern[str] = re.compile(r"(?<!!)\[\[([^\[\]|]+?)(?:\|[^\[\]]*)?\]\]")
+
+# Transclusions: ![[target]] including anchors (#Heading, #^block).
+# Group 1 = raw target text.
+_TRANSCLUSION_RE: re.Pattern[str] = re.compile(r"!\[\[([^\[\]]+?)\]\]")
+
+# Block-ref IDs DEFINED in body: ^blockid at end of line.
+# Negative lookbehind for [ and # to avoid matching inside wikilinks.
+_BLOCKREF_DEF_RE: re.Pattern[str] = re.compile(
+    r"(?<![\[#])\^([A-Za-z0-9][A-Za-z0-9-]*)(?=\s*$)", re.MULTILINE
+)
+
+# ATX headings: # text (with optional trailing ##).
+_HEADING_RE: re.Pattern[str] = re.compile(
+    r"^#{1,6}[ \t]+(.+?)(?:[ \t]+#+)?$", re.MULTILINE
+)
+
+# Inline body tags: #tagname preceded by whitespace or start of line.
+# Excludes headings (which also start with #) because headings have space AFTER #.
+# This matches Obsidian-style inline tags.
+_INLINE_TAG_RE: re.Pattern[str] = re.compile(
+    r"(?:^|(?<=\s))#([A-Za-zÀ-ɏͰ-Ͽ一-龥_]"
+    r"[^\s#,;!@$%^&*()\[\]{}'\"<>?/\\|`]*)",
+    re.MULTILINE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Public exceptions + types
+# ---------------------------------------------------------------------------
+
+
+class ManifestError(BrainError):
+    """Raised on manifest read/parse failures or version mismatches."""
+
+
+@dataclass(frozen=True)
+class SlugEntry:
+    """Per-slug record stored in the manifest."""
+
+    fingerprint: str
+    output_path: str
+    source_path: str
+
+
+@dataclass(frozen=True)
+class Manifest:
+    """Deserialised fastpath ``manifest.json``."""
+
+    version: int
+    parent_build_id: str
+    built_at_ms: int
+    slugs: dict[str, SlugEntry]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def read_manifest(dir: Path) -> Manifest:
+    """Read + parse ``manifest.json`` from ``dir``.
+
+    Raises :class:`ManifestError` on missing file, JSON parse error, or
+    ``version`` mismatch.
+    """
+    path = dir / "manifest.json"
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ManifestError(f"cannot read manifest at {path}: {exc}") from exc
+    try:
+        data: Any = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ManifestError(f"malformed manifest JSON at {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ManifestError(
+            f"manifest root must be a JSON object, got {type(data).__name__}"
+        )
+    version = data.get("version")
+    if version != FINGERPRINT_VERSION:
+        raise ManifestError(
+            f"manifest version {version!r} != current FINGERPRINT_VERSION "
+            f"{FINGERPRINT_VERSION}"
+        )
+    try:
+        slugs: dict[str, SlugEntry] = {
+            k: SlugEntry(
+                fingerprint=str(v["fingerprint"]),
+                output_path=str(v["output_path"]),
+                source_path=str(v["source_path"]),
+            )
+            for k, v in data.get("slugs", {}).items()
+        }
+    except (KeyError, TypeError) as exc:
+        raise ManifestError(f"malformed manifest slugs at {path}: {exc}") from exc
+    return Manifest(
+        version=int(data["version"]),
+        parent_build_id=str(data.get("parent_build_id", "")),
+        built_at_ms=int(data.get("built_at_ms", 0)),
+        slugs=slugs,
+    )
+
+
+def compute_fingerprint(
+    *,
+    source_bytes: bytes,
+    slug: str,
+    source_path: str,
+    output_path: str,
+) -> str:
+    """Compute the structural fingerprint for a vault file.
+
+    Decodes ``source_bytes`` (UTF-8), parses YAML frontmatter, validates all
+    keys against the structural and ignored lists, extracts wikilinks /
+    transclusions / block-refs / heading anchors from the body, builds the
+    canonical blob per the fingerprint spec, and returns sha256 hex.
+
+    ``slug`` and ``output_path`` are caller-supplied because the classifier
+    (T3) reads them directly from the manifest entry it is validating — the
+    manifest already stores both values from the full build, so the classifier
+    never needs to re-implement Quartz's ``slugifyFilePath()`` or
+    output-path derivation.
+
+    Raises :class:`ManifestError` on:
+    - ``source_bytes`` not valid UTF-8
+    - YAML frontmatter parse error
+    - Unknown frontmatter field (not in structural or Appendix A ignored list)
+    - Any other unrecoverable input issue
+    """
+    blob = _compute_canonical_blob(
+        source_bytes=source_bytes,
+        slug=slug,
+        source_path=source_path,
+        output_path=output_path,
+    )
+    return hashlib.sha256(blob).hexdigest()
+
+
+def compute_fingerprint_with_blob(
+    *,
+    source_bytes: bytes,
+    slug: str,
+    source_path: str,
+    output_path: str,
+) -> tuple[str, bytes]:
+    """Like :func:`compute_fingerprint` but also returns the raw canonical blob.
+
+    Intended for debugging parity failures — the blob hex lets maintainers
+    diff TS and Python byte-by-byte to identify which section diverges.
+    """
+    blob = _compute_canonical_blob(
+        source_bytes=source_bytes,
+        slug=slug,
+        source_path=source_path,
+        output_path=output_path,
+    )
+    return hashlib.sha256(blob).hexdigest(), blob
+
+
+# ---------------------------------------------------------------------------
+# Private helpers — shared computation core
+# ---------------------------------------------------------------------------
+
+
+def _compute_canonical_blob(
+    *,
+    source_bytes: bytes,
+    slug: str,
+    source_path: str,
+    output_path: str,
+) -> bytes:
+    """Parse ``source_bytes``, validate frontmatter, build and return the blob.
+
+    Shared by :func:`compute_fingerprint` and :func:`compute_fingerprint_with_blob`.
+    """
+    try:
+        source = source_bytes.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ManifestError(f"source bytes are not valid UTF-8: {exc}") from exc
+
+    try:
+        fields, body = parse_frontmatter(source)
+    except (yaml.YAMLError, ValueError) as exc:
+        raise ManifestError(f"YAML frontmatter parse error: {exc}") from exc
+
+    # Validate all frontmatter keys — unknown keys force non-trivial.
+    for key in fields:
+        if key not in _STRUCTURAL_FIELDS and key not in _IGNORED_FIELDS:
+            raise ManifestError(
+                f"unknown frontmatter field {key!r} — not in structural list or "
+                "Appendix A ignored list; add to spec and bump FINGERPRINT_VERSION"
+            )
+
+    # SECTION_FRONTMATTER: structural fields + YAML-only tags.
+    fm_json = _build_frontmatter_json(fields)
+
+    # SECTION_TAGS: merged YAML tags + inline body tags, sorted, deduped.
+    yaml_tags = _get_str_list(fields.get("tags"))
+    inline_tags = _extract_inline_tags(body)
+    merged_tags = sorted(set(yaml_tags) | set(inline_tags))
+    tags_str = "\n".join(merged_tags)
+
+    # SECTION_WIKILINKS
+    wikilinks_str = "\n".join(sorted(set(_extract_wikilinks(body))))
+
+    # SECTION_TRANSCLUSIONS
+    transclusions_str = "\n".join(sorted(set(_extract_transclusions(body))))
+
+    # SECTION_BLOCK_REFS
+    block_refs_str = "\n".join(sorted(set(_extract_block_refs(body))))
+
+    # SECTION_HEADING_ANCHORS (document order — NOT sorted)
+    headings_str = "\n".join(_extract_heading_anchors(body))
+
+    return _build_canonical_blob(
+        slug=slug,
+        source_path=source_path,
+        output_path=output_path,
+        frontmatter_json=fm_json,
+        tags_str=tags_str,
+        wikilinks_str=wikilinks_str,
+        transclusions_str=transclusions_str,
+        block_refs_str=block_refs_str,
+        headings_str=headings_str,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Private helpers — canonical blob encoding
+# ---------------------------------------------------------------------------
+
+
+def _u32be(n: int) -> bytes:
+    return struct.pack(">I", n)
+
+
+def _encode_section(s: str) -> bytes:
+    encoded = s.encode("utf-8")
+    return _u32be(len(encoded)) + encoded
+
+
+def _build_canonical_blob(
+    *,
+    slug: str,
+    source_path: str,
+    output_path: str,
+    frontmatter_json: str,
+    tags_str: str,
+    wikilinks_str: str,
+    transclusions_str: str,
+    block_refs_str: str,
+    headings_str: str,
+) -> bytes:
+    """Assemble the 10-section canonical blob per the fingerprint spec."""
+    return b"".join([
+        _u32be(FINGERPRINT_VERSION),           # SECTION_VERSION: just u32be, no length prefix
+        _encode_section(slug),                 # SECTION_SLUG
+        _encode_section(source_path),          # SECTION_SOURCE_PATH
+        _encode_section(output_path),          # SECTION_OUTPUT_PATH
+        _encode_section(frontmatter_json),     # SECTION_FRONTMATTER
+        _encode_section(tags_str),             # SECTION_TAGS
+        _encode_section(wikilinks_str),        # SECTION_WIKILINKS
+        _encode_section(transclusions_str),    # SECTION_TRANSCLUSIONS
+        _encode_section(block_refs_str),       # SECTION_BLOCK_REFS
+        _encode_section(headings_str),         # SECTION_HEADING_ANCHORS
+    ])
+
+
+# ---------------------------------------------------------------------------
+# Private helpers — frontmatter JSON blob
+# ---------------------------------------------------------------------------
+
+
+def _normalize_date_val(val: Any) -> str | None:
+    """Serialize a YAML date/datetime/string to ISO 8601, or None.
+
+    Midnight ``datetime.datetime`` objects are truncated to date-only to match
+    TS ``_normalizeDateVal`` behaviour: js-yaml parses bare YAML date scalars
+    (e.g. ``date: 2024-03-15``) as UTC-midnight ``Date`` objects, which the TS
+    side normalises back to a ``"YYYY-MM-DD"`` string.  Python pyyaml produces
+    ``datetime.date`` for bare dates (already date-only) and
+    ``datetime.datetime`` for bare date-times; truncating the midnight case
+    keeps both sides byte-identical.
+
+    Examples::
+
+        datetime.date(2024, 3, 15)              → "2024-03-15"
+        datetime.datetime(2024, 3, 15, 0, 0, 0) → "2024-03-15"   # midnight truncated
+        datetime.datetime(2024, 3, 15, 12, 0, 0)→ "2024-03-15T12:00:00"
+    """
+    if val is None:
+        return None
+    if isinstance(val, datetime):
+        # Truncate midnight datetimes to date-only, matching TS _normalizeDateVal.
+        if (
+            val.hour == 0
+            and val.minute == 0
+            and val.second == 0
+            and val.microsecond == 0
+        ):
+            return val.date().isoformat()
+        return val.isoformat()
+    if isinstance(val, date):
+        return val.isoformat()
+    if isinstance(val, str):
+        return val
+    return str(val)
+
+
+def _get_str_list(val: Any) -> list[str]:
+    """Coerce a YAML value to a list of strings."""
+    if val is None:
+        return []
+    if isinstance(val, list):
+        return [str(x) for x in val if x is not None]
+    if isinstance(val, str):
+        return [val]
+    return []
+
+
+def _build_frontmatter_json(fields: dict[str, Any]) -> str:
+    """Build deterministic structural frontmatter JSON (no whitespace, exact key order).
+
+    Encodes YAML-only tags (not merged with inline body tags) per the spec.
+    """
+    obj: dict[str, Any] = {}
+    for key in _STRUCTURAL_FIELD_ORDER:
+        if key in _ARRAY_FIELDS:
+            if key not in fields or fields[key] is None:
+                obj[key] = None
+            else:
+                obj[key] = sorted(_get_str_list(fields[key]))
+        elif key in _BOOL_FIELDS:
+            val = fields.get(key)
+            obj[key] = bool(val) if val is not None else None
+        elif key in _DATE_FIELDS:
+            obj[key] = _normalize_date_val(fields.get(key))
+        else:
+            val = fields.get(key)
+            obj[key] = str(val) if val is not None else None
+    return json.dumps(obj, separators=(",", ":"), ensure_ascii=False)
+
+
+# ---------------------------------------------------------------------------
+# Private helpers — body parsing
+# ---------------------------------------------------------------------------
+
+
+def _extract_inline_tags(body: str) -> list[str]:
+    """Extract inline ``#tags`` from body text (Obsidian-style)."""
+    return [m.group(1) for m in _INLINE_TAG_RE.finditer(body)]
+
+
+def _extract_wikilinks(body: str) -> list[str]:
+    """Extract non-transclusion wikilink targets (raw text, including anchors)."""
+    return [m.group(1).strip() for m in _WIKILINK_RE.finditer(body) if m.group(1).strip()]
+
+
+def _extract_transclusions(body: str) -> list[str]:
+    """Extract transclusion targets (``![[...]]``, including anchors)."""
+    return [m.group(1).strip() for m in _TRANSCLUSION_RE.finditer(body) if m.group(1).strip()]
+
+
+def _extract_block_refs(body: str) -> list[str]:
+    """Extract block-ref IDs defined in body (``^blockid`` at end of line)."""
+    return [m.group(1) for m in _BLOCKREF_DEF_RE.finditer(body)]
+
+
+def _extract_heading_anchors(body: str) -> list[str]:
+    """Return heading anchors in document order using github-slugger semantics."""
+    slugger = Slugger()
+    return [slugger.slug(m.group(1).strip()) for m in _HEADING_RE.finditer(body)]