Living Document Notice
Published 2026-09-18. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Deterministic Frontmatter Validation and Fail-Closed Schema Gates

Summary

YAML frontmatter serves as the canonical contract between Markdown text documents and structured relational projections. However, permissive YAML parsers routinely introduce silent data corruption through ambiguous type coercion, tab-indentation parsing failures, and unvalidated date formats. Bosun PKM implements a deterministic, fail-closed schema validation gate that enforces strict type adherence, rejects malformed syntax early, and routes unverified notes to quarantine reviews.

Failure Modes in Permissive YAML Ingestion

Standard YAML 1.1 parsers exhibit well-documented coercion hazards when ingesting personal notes:

• The string NO or OFF coerced to boolean false.
• Unquoted ISO timestamps like 2026-09-18 parsed as platform-dependent date objects rather than canonical strings.
• Mixed tab and space indentation producing undetected syntax parsing aborts.
• Missing closing delimiter (---) causing the entire document body to be treated as frontmatter metadata.

YAML Ingestion Ambiguities:
title: 2026-09-18           -> Coerced to datetime or float depending on parser dialect
public: yes                 -> Coerced to boolean True instead of string
tags: [systems, ops]        -> Parsed as array
tags: systems, ops          -> Parsed as single comma-separated string

When downstream systems expect strongly typed frontmatter dictionaries, silent type coercion corrupts publication filters and search indexes.

The 20-Field Canonical Validation Contract

To guarantee schema integrity, Bosun PKM subjects notes entering the digital garden review pipeline to a strict 20-field validation gate:

---
title: "Deterministic Frontmatter Validation"
description: "Fail-closed schema validation gate for markdown frontmatter."
aliases: []
tags:
  - dispatch
  - validation
garden_status: candidate        # Enum: imported, candidate, evergreen, published, rejected
public: true                   # Strict boolean: true or false
review_status: needs-review    # Enum: needs-review, needs-redaction, needs-provenance, approved, rejected
privacy_level: public          # Enum: private, internal, public
source_vault: "stax-digital-garden"
source_path: "02 Review/bosun-pkm/note.md"
source_sha256: "7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069"
imported_at: "2026-09-18T12:00:00Z"
redaction_required: false
publication_status: draft      # Enum: draft, approved, published, archived
canonical_url: "https://garden.bosunpkm.com/02-Review/bosun-pkm/note"
approved_by: null
approved_at: null
updated: "2026-09-18T12:00:00Z"
---

Fail-Closed Parser Implementation

The frontmatter validator uses a lightweight, tab-rejecting parser that enforces exact syntax boundaries:

import re
from typing import Any

REQUIRED_CANONICAL_FIELDS = {
    "title", "description", "aliases", "tags",
    "garden_status", "public", "review_status", "privacy_level",
    "source_vault", "source_path", "source_sha256", "imported_at",
    "redaction_required", "publication_status",
    "canonical_url", "approved_by", "approved_at", "updated"
}

ISO8601_PATTERN = re.compile(
    r"^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?)?$"
)

class ValidationError(Exception):
    pass

def validate_frontmatter_block(raw_text: str) -> dict[str, Any]:
    lines = raw_text.splitlines()
    if not lines or lines[0].strip() != "---":
        raise ValidationError("Document missing opening '---' delimiter")

    close_idx = -1
    for idx, line in enumerate(lines[1:], start=1):
        if line.strip() in ("---", "..."):
            close_idx = idx
            break

    if close_idx == -1:
        raise ValidationError("Unclosed frontmatter block: missing closing '---'")

    yaml_block = lines[1:close_idx]
    for line_num, line in enumerate(yaml_block, start=2):
        if line.startswith("\t"):
            raise ValidationError(f"Tab indentation detected on line {line_num}")

    parsed = parse_strict_yaml("\n".join(yaml_block))
    missing_keys = REQUIRED_CANONICAL_FIELDS - set(parsed.keys())
    if missing_keys:
        raise ValidationError(f"Missing required frontmatter keys: {sorted(missing_keys)}")

    return parsed

Demotion Mechanics for Invalid States

When validation fails, the engine never discards or overwrites user notes. Instead, it applies a fail-closed demotion policy:

1. The note remains on disk in its original location.
2. The database projection marks review_status = "needs-review" and public = false.
3. The note is excluded from Directus API publication and Quartz static builds until manually remediated.

This fail-closed architecture protects public publications from accidental data leaks or malformed layouts while maintaining full local document durability.