@jasonbelmonti/markdown-engine 2.0.0 → 3.1.0

package/docs/contracts/declarative-validation.md

@@ -1,19 +1,41 @@
 # Declarative Validation Contract
 
-Status: package 2.0.0, v1 profile syntax, document contract 1.0.0
-Last updated: 2026-05-14
+Status: package 3.0.0, v1 profile syntax with v2 Conditional V2, document contract 1.0.0
+Last updated: 2026-06-15
+Current v2 surface: flat-rule result/evidence shell, ID count-bound schema and
+runtime evaluator contract, plus `tableColumnCoverage` schema, compiled-plan,
+and runtime evaluator contract, `frontmatterShape` schema, compiled-plan, and
+runtime evaluator contract, `textFormat` schema, compiled-plan, and runtime
+evaluator contract, grouped rule runtime contract, and rule-level `when`
+schema, matcher, public skipped-rule result, skipped counts, and evidence
+cloning contract.
 
 This document defines the public declarative validation contract for
 `@jasonbelmonti/markdown-engine`. The stable surface is the package-root API,
-the v1 profile syntax, the CLI validation command, diagnostic codes, serialized
-result shapes, and evidence fields. Internal parser output, compiled rule-plan
-records, selector target records, and evaluator implementation modules are not
-public contracts.
-
-Package 2.0 does not introduce `documentVersion: "2.0.0"` or
-`markdown-engine.validation@v2`. Declarative validation continues to use the v1
-profile syntax against the existing `documentVersion: "1.0.0"` rich IR
-document contract.
+the v1 profile syntax, the admitted v2 profile syntax and runtime subset, the
+CLI validation command, diagnostic codes, serialized result shapes, and evidence
+fields. Internal parser output, compiled rule-plan records, selector target
+records, and evaluator implementation modules are not public contracts.
+
+Package 3.0 does not introduce `documentVersion: "3.0.0"` or CLI JSON
+discrimination.
+Declarative validation continues to use the existing `documentVersion: "1.0.0"`
+rich IR document contract, while the profile admission path recognizes
+`markdown-engine.validation@v2` for the same flat rule shape with `id`, optional
+`severity`, `select`, and `assert`; non-recursive `anyOf` and `allOf`; and
+optional rule-level `when`. The admitted v2 path exposes the result and evidence
+shell needed to distinguish assertion, grouped, and skipped evaluation output
+from v1 output, plus the ID count-bound schema, compiled-plan, and runtime
+evaluator contract; the `tableColumnCoverage` schema, compiled-plan, and
+runtime evaluator contract; the `frontmatterShape` schema, private
+compiled-plan, and runtime evaluator contract; the `textFormat` schema,
+private compiled-plan, and runtime evaluator contract; and the `when` schema
+plus private compiled-plan and matcher contract. Matched applicability
+continues into normal rule evaluation.
+Non-matching applicability returns a public skipped rule result with
+`status: "skipped"`, `passed: true`, `evaluation.kind: "skipped"`,
+`reason: "whenNotMatched"`, `skippedRuleCount`, no top-level diagnostics, and a
+nested `when` applicability result.
 
 ## 1.0 Contract
 
@@ -36,6 +58,11 @@ validateWithProfile(
   profile: ValidationProfile,
   options?: DeclarativeValidationOptions,
 ): DeclarativeValidationResult
+
+validateDocumentSet(
+  entries: readonly ValidateDocumentSetEntry[],
+  options?: ValidateDocumentSetOptions,
+): ValidateDocumentSetResult
 ```
 
 Compiled declarative validation plans are internal. They are not exported from
@@ -53,8 +80,28 @@ syntaxVersion: markdown-engine.validation@v1
 `syntaxVersion` is required. Missing or unsupported values emit
 `profile.config.unsupportedSyntaxVersion`.
 
-The v1 vocabulary is closed. Unknown profile keys, rule keys, selector keys,
-known assertion keys, and nested assertion keys emit
+The v2 syntax is admitted as an additive profile syntax:
+
+```yaml
+syntaxVersion: markdown-engine.validation@v2
+```
+
+This release recognizes v2 as a distinct syntax version at profile admission,
+admits ID count bounds at the schema, compiled-plan, and runtime evaluator
+layers, admits `tableColumnCoverage` at the schema, internal compiled-plan, and
+runtime evaluator layers, admits `frontmatterShape` at the schema, internal
+compiled-plan, and runtime evaluator layers, admits `textFormat` at the schema,
+internal compiled-plan, and runtime evaluator layers, admits non-recursive
+grouped rules at the schema, compiled-plan, and runtime evaluator layers, and
+admits optional rule-level `when` at the schema, internal compiled-plan, and
+matcher layers.
+Matching `when` rules continue through normal flat or grouped evaluation and do
+not add a public `when` field to the evaluated rule result. Non-matching `when`
+rules are not evaluated; they return the public skipped-rule result shape,
+increment `skippedRuleCount`, and leave `evaluatedRuleCount` unchanged.
+
+The admitted v1/v2 flat vocabulary is closed. Unknown profile keys, rule keys,
+selector keys, known assertion keys, and nested assertion keys emit
 `profile.config.unsupportedKey` unless the contract assigns a more specific
 compile diagnostic for an unsupported selector target or unsupported assertion
 member.
@@ -113,15 +160,52 @@ results, and does not evaluate rules.
 The top-level profile shape is:
 
 ```ts
+type ValidationProfileSyntaxVersion =
+  | "markdown-engine.validation@v1"
+  | "markdown-engine.validation@v2";
+
 interface ValidationProfile {
-  syntaxVersion: "markdown-engine.validation@v1";
+  syntaxVersion: ValidationProfileSyntaxVersion;
   documentVersion?: EngineDocumentVersion;
   rules: readonly DeclarativeValidationRule[];
 }
 
-interface DeclarativeValidationRule {
+type DeclarativeValidationRule =
+  | DeclarativeValidationFlatRule
+  | DeclarativeValidationGroupRule;
+
+interface DeclarativeValidationRuleFields {
   id: string;
   severity?: "error" | "warning" | "info";
+  when?: DeclarativeValidationApplicability;
+}
+
+interface DeclarativeValidationFlatRule extends DeclarativeValidationRuleFields {
+  select: DeclarativeSelector;
+  assert: DeclarativeAssertion;
+}
+
+interface DeclarativeValidationApplicability {
+  select: DeclarativeSelector;
+  assert: DeclarativeAssertion;
+}
+
+type DeclarativeValidationGroupRule =
+  | DeclarativeValidationAnyOfRule
+  | DeclarativeValidationAllOfRule;
+
+interface DeclarativeValidationAnyOfRule
+  extends DeclarativeValidationRuleFields {
+  anyOf: readonly DeclarativeValidationBranch[];
+}
+
+interface DeclarativeValidationAllOfRule
+  extends DeclarativeValidationRuleFields {
+  allOf: readonly DeclarativeValidationBranch[];
+}
+
+interface DeclarativeValidationBranch {
+  label?: string;
   select: DeclarativeSelector;
   assert: DeclarativeAssertion;
 }
@@ -134,6 +218,11 @@ evidence identify output by `ruleId`.
 Rule `severity` defaults to `error` when omitted. Unsupported severity values
 emit `profile.config.invalidShape`.
 
+Rule-level `when` is allowed only on v2 rules. Branch-level `when` remains
+unsupported. V1 profiles preserve the original flat rule authoring contract;
+grouped `anyOf` / `allOf`, ID count bounds, `tableColumnCoverage`,
+`frontmatterShape`, `textFormat`, and rule-level `when` are v2 additions.
+
 Profile values must be JSON-safe data properties after YAML materialization.
 Functions, accessors, proxies, cyclic structures, sparse arrays, `undefined`
 payloads in required positions, non-finite numbers, and `__proto__` properties
@@ -203,11 +292,36 @@ interface DeclarativeAssertion {
     prefix?: string;
     unique?: boolean;
     caseSensitive?: boolean;
+    minCount?: number;
+    maxCount?: number;
   };
   references?: {
     idsFrom: { section?: string; column?: string; prefix?: string };
     mustAppearIn: readonly string[];
   };
+  tableColumnCoverage?: {
+    source: {
+      section: string;
+      column: string;
+      prefix?: string;
+      caseSensitive?: boolean;
+    };
+    target: {
+      section: string;
+      tableHeader?: readonly string[];
+      column: string;
+    };
+    require: "everySourceId";
+  };
+  frontmatterShape?: {
+    presence?: "required" | "forbidden";
+    fields?: readonly {
+      field: string;
+      required?: true;
+      valueType?: "string" | "number" | "boolean" | "array" | "object" | "null";
+      nonEmpty?: true;
+    }[];
+  };
   text?: {
     contains?: string;
     excludes?: readonly string[];
@@ -220,6 +334,9 @@ interface DeclarativeAssertion {
     min?: number;
     max?: number;
   };
+  textFormat?: {
+    format: "isoDate";
+  };
   frontmatterRequired?: {
     fields: readonly string[];
   };
@@ -242,9 +359,12 @@ Selector/assertion compatibility is part of the public contract:
 | `tableColumnsRequired` | `table` |
 | `ids` | all supported selector targets |
 | `references` | `document` |
+| `tableColumnCoverage` | `document` |
+| `frontmatterShape` | `document` |
 | `text` | all supported selector targets |
 | `textOccurrenceCount` | all supported selector targets |
 | `textLength` | all supported selector targets |
+| `textFormat` | all supported selector targets |
 | `frontmatterRequired` | `document` |
 
 Incompatible supported selector/assertion pairs emit
@@ -258,9 +378,61 @@ resolves zero targets.
 headings appear as an ordered subsequence in the normalized section tree
 flattened in source order.
 
-`ids.unique` must be `true`; `prefix` and `caseSensitive` are modifiers, not
-standalone predicates. `caseSensitive` defaults to `true`. ID tokens use the
+For v1 profiles, `ids.unique` must be `true`. For v2 profiles, `ids.unique`
+must be `true` when provided and may be omitted when `ids.minCount` or
+`ids.maxCount` provides the predicate. `prefix` and `caseSensitive` are modifiers,
+not standalone predicates. `caseSensitive` defaults to `true`. ID tokens use the
 documented token grammar `[A-Za-z][A-Za-z0-9]*-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*`.
+For v2 profiles, `ids.minCount` and `ids.maxCount` are admitted as non-negative
+integer schema and compiled-plan fields. When both are present, `minCount` must
+be less than or equal to `maxCount`. Runtime count evaluation uses unique
+comparison values after prefix filtering and duplicate occurrence de-duplication.
+Failed lower and upper bounds emit `profile.validation.idCountTooLow` and
+`profile.validation.idCountTooHigh`.
+
+For v2 profiles, `tableColumnCoverage` is admitted as a flat-rule schema and
+internal compiled-plan assertion. It is compatible only with a `document`
+selector because the assertion owns its source and target table-column inputs.
+`source.section`, `source.column`, `target.section`, and `target.column` are
+required non-empty strings. `source.prefix` is optional and must be non-empty
+when provided. `source.caseSensitive` is optional and defaults to `true` in the
+compiled plan. `target.tableHeader` is an optional non-empty string array.
+`require` must be exactly `"everySourceId"`. Runtime evaluation extracts unique
+source IDs from `source.section` and `source.column`, applies `source.prefix`
+and `source.caseSensitive`, and requires every source ID comparison value to
+appear in the configured target table column. IDs appearing elsewhere in the
+target section do not satisfy coverage. Missing target sections, missing target
+columns, and missing target-column IDs emit deterministic validation diagnostics
+source-grounded to the source ID when source evidence is available.
+
+For v2 profiles, `frontmatterShape` is admitted as a flat-rule schema and
+internal compiled-plan assertion. It is compatible only with a `document`
+selector because frontmatter is document metadata. `presence` is optional and
+must be exactly `"required"` or `"forbidden"` when provided. `fields` is an
+optional non-empty array of field constraints. Each field constraint has a
+required non-empty `field` name and must include at least one effective
+constraint: `required: true`, `valueType`, or `nonEmpty: true`. Field names
+within one `frontmatterShape.fields` array must be unique. `valueType` must be
+one of `"string"`, `"number"`, `"boolean"`, `"array"`, `"object"`, or `"null"`.
+`nonEmpty: true` is a string predicate; when it is combined with `valueType`,
+`valueType` must be `"string"`. `presence: "forbidden"` cannot be combined with
+`fields`.
+
+Runtime evaluation treats frontmatter as present when
+`document.frontmatter !== undefined`. `presence: "required"` fails absent
+frontmatter with `profile.validation.frontmatterMissing`.
+`presence: "forbidden"` fails any present frontmatter value, including empty
+frontmatter, with `profile.validation.frontmatterForbidden`. Field constraints
+evaluate only top-level frontmatter fields and do not coerce values. A required
+field that is absent, or any required field on non-object frontmatter, emits
+`profile.validation.frontmatterFieldMissing`. Optional fields are ignored when
+absent. `valueType` checks distinguish `"string"`, finite `"number"`,
+`"boolean"`, `"array"`, plain `"object"`, and `"null"` values and emit
+`profile.validation.frontmatterFieldTypeMismatch` on mismatch. `nonEmpty: true`
+requires a present field value to be a non-empty string and emits
+`profile.validation.frontmatterFieldEmpty` when that predicate fails. When
+`valueType: "string"` and `nonEmpty: true` are combined, a non-string value
+emits the type-mismatch diagnostic without a duplicate empty-string diagnostic.
 
 `text` must include `contains` or a non-empty `excludes` array.
 `textOccurrenceCount.count` is a finite number and counts non-overlapping
@@ -270,10 +442,22 @@ integers, `min` must be less than or equal to `max` when both are present, and
 evaluation uses JavaScript string `.length` for each selected target's
 normalized text.
 
+For v2 profiles, `textFormat` is admitted as a flat-rule schema and internal
+compiled-plan assertion. `textFormat.format` must be exactly `"isoDate"`;
+custom formats, locale options, regex-like formats, profile-supplied patterns,
+and additional `textFormat` members are unsupported. Runtime evaluation checks
+each selected target's normalized text as an exact real calendar date in
+`YYYY-MM-DD` form. Valid dates such as `2026-06-14` and leap dates such as
+`2024-02-29` pass. Non-dates, invalid calendar dates, timestamps, partial
+dates, and strings with extra text fail with
+`profile.validation.assertionFailed`. The evaluator does not compile
+profile-supplied regular expressions, call `Date.parse`, perform locale
+parsing, or implement date ordering.
+
 Empty selector results produce `profile.validation.emptySelection` for exists,
-table, ID, reference, text, occurrence, and text-length assertions.
-Document-scoped required-section and required-frontmatter assertions evaluate
-against the document.
+table, ID, reference, text, occurrence, text-length, and text-format
+assertions. Document-scoped required-section, required-frontmatter, and
+frontmatter-shape assertions evaluate against the document.
 
 ## Diagnostics
 
@@ -284,11 +468,17 @@ error severity. Validation diagnostics use the rule severity. Source ranges are
 included when a selected target has source evidence; locations are omitted
 rather than fabricated when unavailable.
 
+Rule-level `when` uses the existing validation diagnostic codes. When
+applicability does not match, those diagnostics are cloned into
+`ruleResults[].when.diagnostics`; they are not promoted into top-level
+`diagnostics`, so a skipped rule with a nested error-severity applicability
+diagnostic can still leave the aggregate `valid` value `true`.
+
 | Code | Severity source | Emitted when |
 | --- | --- | --- |
 | `profile.config.invalidYaml` | `error` | YAML text cannot be parsed or materialized as JSON-safe profile data. |
 | `profile.config.yamlWarning` | `warning` | YAML materialization produces a non-fatal parser warning. |
-| `profile.config.unsupportedSyntaxVersion` | `error` | `syntaxVersion` is missing or is not `markdown-engine.validation@v1`. |
+| `profile.config.unsupportedSyntaxVersion` | `error` | `syntaxVersion` is missing or is not `markdown-engine.validation@v1` or `markdown-engine.validation@v2`. |
 | `profile.config.invalidShape` | `error` | Required fields are missing, fields have wrong types, arrays or strings are empty, rule IDs duplicate, scalar values are invalid, table predicates are ineffective, or assertion payloads contain no effective predicate. |
 | `profile.config.documentVersionMismatch` | `error` | Resolved profile `documentVersion` differs from the supplied `EngineDocument.version`. |
 | `profile.config.unsupportedKey` | `error` | A closed profile, rule, selector, known assertion object, nested object, regex-like key, executable-like key, or direct typed profile object contains unsupported syntax. |
@@ -296,15 +486,24 @@ rather than fabricated when unavailable.
 | `profile.compile.unsupportedAssertion` | `error` | Parsed YAML or JSON-safe `assert` input contains an unsupported first-level assertion member that does not have unsupported-key precedence. |
 | `profile.compile.incompatibleSelectorAssertion` | `error` | A supported selector target is paired with an incompatible supported assertion. |
 | `profile.validation.emptySelection` | Rule severity | A rule cannot evaluate because its selector matches no applicable target. |
-| `profile.validation.assertionFailed` | Rule severity | A supported assertion evaluates and fails without a more specific diagnostic code, including missing table columns, exact occurrence-count mismatches, and text-length bound failures. |
+| `profile.validation.assertionFailed` | Rule severity | A supported assertion evaluates and fails without a more specific diagnostic code, including missing table columns, exact occurrence-count mismatches, text-length bound failures, and text-format `isoDate` failures. |
 | `profile.validation.duplicateId` | Rule severity | An `ids.unique` assertion finds repeated IDs. |
+| `profile.validation.frontmatterForbidden` | Rule severity | A `frontmatterShape` assertion with `presence: "forbidden"` finds present frontmatter. |
+| `profile.validation.frontmatterFieldEmpty` | Rule severity | A frontmatter field configured with `nonEmpty: true` is not a non-empty string. |
 | `profile.validation.frontmatterFieldMissing` | Rule severity | A required frontmatter field is absent. |
+| `profile.validation.frontmatterFieldTypeMismatch` | Rule severity | A frontmatter field value does not match the configured `frontmatterShape.fields[].valueType` without coercion. |
+| `profile.validation.frontmatterMissing` | Rule severity | A `frontmatterShape` assertion with `presence: "required"` finds absent frontmatter. |
+| `profile.validation.idCountTooHigh` | Rule severity | Unique ID count after filtering is higher than `ids.maxCount`. |
+| `profile.validation.idCountTooLow` | Rule severity | Unique ID count after filtering is lower than `ids.minCount`. |
 | `profile.validation.referenceMissing` | Rule severity | A source ID is absent from a required target section. |
 | `profile.validation.sectionMissing` | Rule severity | A required section heading is absent. |
 | `profile.validation.sectionOrder` | Rule severity | A strict required-section order cannot be satisfied. |
+| `profile.validation.tableColumnCoverageIdMissing` | Rule severity | A source ID is absent from the configured target table column. |
+| `profile.validation.tableColumnCoverageTargetColumnMissing` | Rule severity | The configured target table column cannot be resolved. |
+| `profile.validation.tableColumnCoverageTargetSectionMissing` | Rule severity | The configured target section cannot be resolved. |
 | `profile.validation.textExcluded` | Rule severity | A selected target contains forbidden literal text. |
 | `profile.validation.textMissing` | Rule severity | A selected target lacks required literal text from a `text.contains` assertion. |
-| `profile.validation.assertionUnsupported` | `error` | A compiled assertion has no evaluator implementation; this is an internal safety diagnostic. |
+| `profile.validation.assertionUnsupported` | `error` | A compiled assertion or compiled assertion feature has no evaluator implementation; this is an internal safety diagnostic. |
 
 ## Result Shape
 
@@ -314,9 +513,12 @@ rather than fabricated when unavailable.
 interface DeclarativeValidationResult extends ValidationResult {
   valid: boolean;
   diagnostics: readonly MarkdownDiagnostic[];
-  ruleResults: readonly ValidationRuleResult[];
+  ruleResults: readonly (
+    | ValidationRuleResult
+    | DeclarativeValidationRuleResultV2
+  )[];
   profile: {
-    syntaxVersion: "markdown-engine.validation@v1";
+    syntaxVersion: ValidationProfileSyntaxVersion;
     documentVersion: EngineDocumentVersion;
     ruleCount: number;
   };
@@ -324,9 +526,61 @@ interface DeclarativeValidationResult extends ValidationResult {
 }
 ```
 
-`valid` is `false` when any error-severity diagnostic exists. Warning and info
-validation diagnostics can make a rule result fail without making the aggregate
-result invalid.
+For admitted v2 profiles, result metadata records
+`syntaxVersion: "markdown-engine.validation@v2"`, `evaluatedRuleCount`, and
+`skippedRuleCount`. V2 rule results include the v1-compatible `ruleId`,
+`passed`, and `diagnostics` fields plus `status`, optional skipped
+applicability metadata, and flat, grouped, or skipped evaluation metadata:
+
+```ts
+interface DeclarativeValidationRuleResultV2 extends ValidationRuleResult {
+  status: "passed" | "failed" | "skipped";
+  when?: DeclarativeValidationApplicabilityResult;
+  evaluation:
+    | { kind: "assertions"; diagnostics: readonly MarkdownDiagnostic[] }
+    | {
+        kind: "anyOf";
+        selectedBranch?: DeclarativeValidationBranchReference;
+        branches: readonly DeclarativeValidationBranchResult[];
+      }
+    | {
+        kind: "allOf";
+        branches: readonly DeclarativeValidationBranchResult[];
+      }
+    | { kind: "skipped"; reason: "whenNotMatched" };
+}
+
+interface DeclarativeValidationApplicabilityResult {
+  status: "matched" | "notMatched";
+  diagnostics: readonly MarkdownDiagnostic[];
+}
+
+interface DeclarativeValidationBranchReference {
+  branchIndex: number;
+  label?: string;
+}
+
+interface DeclarativeValidationBranchResult
+  extends DeclarativeValidationBranchReference {
+  status: "passed" | "failed";
+  diagnostics: readonly MarkdownDiagnostic[];
+}
+```
+
+For configured `when`, matched applicability continues into normal flat or
+grouped evaluation and contributes one evaluated rule. The evaluated rule result
+does not serialize a `when` field. Non-matching applicability returns one
+skipped rule result with `status: "skipped"`, `passed: true`, empty top-level
+rule `diagnostics`, `when.status: "notMatched"`, nested applicability
+diagnostics, `evaluation.kind: "skipped"`, and `reason: "whenNotMatched"`.
+Skipped rules increment `skippedRuleCount`, do not increment
+`evaluatedRuleCount`, and do not evaluate flat assertions or grouped branches.
+
+`valid` is `false` when any top-level error-severity diagnostic exists in
+`diagnostics`. Nested skipped applicability diagnostics under
+`ruleResults[].when.diagnostics` do not by themselves make the aggregate result
+invalid. Warning and info validation diagnostics can make a rule result fail
+without making the aggregate result invalid.
 
 Rule results are sorted deterministically. Each rule result includes the public
 `ruleId`, `passed`, and cloned diagnostics. Results do not expose compiled rule
@@ -338,16 +592,27 @@ Evidence is emitted only when `DeclarativeValidationOptions.includeEvidence` is
 `true`:
 
 ```ts
-interface DeclarativeValidationEvidence {
+interface DeclarativeValidationEvidence<
+  RuleResult extends ValidationRuleResult = ValidationRuleResult,
+> {
   inputHash: string;
   profileHash: string;
   engineVersion: string;
   runtimeVersion: string;
-  ruleResults: readonly ValidationRuleResult[];
+  ruleResults: readonly RuleResult[];
   diagnostics: readonly MarkdownDiagnostic[];
 }
 ```
 
+For v1 profiles, `ruleResults` contains the unchanged v1 rule-result shape. For
+admitted v2 profiles, `ruleResults` clones the public v2 rule-result shape,
+including `status`, flat assertion evaluation, and grouped `anyOf` / `allOf`
+branch evaluation. Skipped v2 rule results are cloned through evidence in the
+same `ruleResults` array, and `evidence.diagnostics` clones the top-level
+diagnostics array. Evidence does not serialize compiled rule plans, selector
+target records, assertion-specific ID count evidence, or assertion-specific
+table-column coverage evidence.
+
 `inputHash` is a lowercase hexadecimal SHA-256 digest of the stable JSON
 serialization of the supplied normalized `EngineDocument` after omitting only
 the top-level `document.path` field. Structural target paths remain part of the
@@ -360,7 +625,7 @@ serialization of the resolved `ValidationProfile` after applying the resolved
 the same profile hash for the same document version and rules.
 
 `engineVersion` records the package version that produced the evidence. In the
-2.0 release line this is `"2.0.0"` even though `documentVersion` remains
+3.0 release line this is `"3.0.0"` even though `documentVersion` remains
 `"1.0.0"`.
 
 Raw Markdown bytes, raw YAML bytes, YAML comments, caller file paths, and
@@ -384,7 +649,9 @@ validate the Markdown file.
 
 After profile compilation succeeds, the CLI emits a validation-result JSON
 shape whether the document passes or fails. Validation CLI results include
-evidence.
+evidence. V2 CLI results use the same validation-result arm of the CLI JSON
+union; there is no extra CLI discriminator beyond
+`profile.syntaxVersion: "markdown-engine.validation@v2"`.
 
 ## CLI JSON Union
 
@@ -411,23 +678,85 @@ unsupported assertion members, and incompatible selector/assertion pairs. It
 contains no `profile` and no `evidence`.
 
 Validation-result JSON is used after profile compilation succeeds. It contains
-`profile`, `ruleResults`, `diagnostics`, `valid`, and `evidence`.
+`profile`, `ruleResults`, `diagnostics`, `valid`, and `evidence`. For v2
+profiles, that same validation-result JSON can include `evaluatedRuleCount`,
+`skippedRuleCount`, `status: "skipped"`, nested `when` diagnostics, and
+`evaluation.kind: "skipped"`.
 
 ## Exit Codes
 
 | Exit code | Meaning |
 | --- | --- |
-| `0` | Validation completed with no error-severity diagnostics. |
-| `1` | Profile/config/compile, Markdown normalization, document-version mismatch, or validation diagnostics include at least one error. |
+| `0` | Validation completed with no top-level error-severity diagnostics. |
+| `1` | Profile/config/compile, Markdown normalization, document-version mismatch, or top-level validation diagnostics include at least one error. |
 | `2` | CLI usage, unsupported format, unknown argument, missing argument value, repeated singleton flag, unsupported `--document-version`, or local file read error. |
 
 ## Compatibility And Migration
 
 The v1 declarative validation syntax is a durable authoring contract for the
-2.0 package release line. Changes to profile syntax names, selector names,
+3.0 package release line. Changes to profile syntax names, selector names,
 assertion names, result fields, diagnostic codes, CLI flags, CLI JSON shape, or
 evidence hash inputs require explicit compatibility review.
 
+V1 preservation is explicit: v1 authoring syntax, v1 rule result shape, v1
+diagnostic inventory, v1 CLI JSON behavior, and v1 evidence hash inputs remain
+unchanged by the admitted v2 syntax.
+
+Compatibility examples:
+
+```yaml
+# v1 compatibility profile: remains on the v1 authoring and result contract.
+syntaxVersion: markdown-engine.validation@v1
+rules:
+  - id: sections.present
+    select:
+      target: document
+    assert:
+      sectionsRequired:
+        headings:
+          - Mission Brief
+```
+
+```yaml
+# v2 opt-in profile: selects Conditional V2 behavior explicitly.
+syntaxVersion: markdown-engine.validation@v2
+rules:
+  - id: release.docs
+    anyOf:
+      - label: release-section
+        select:
+          target: section
+          title: Release
+        assert:
+          exists: true
+      - label: changelog-link
+        select:
+          target: link
+          text: changelog
+        assert:
+          exists: true
+```
+
+```yaml
+# v2 date-heading profile: validates exact ISO date heading text.
+syntaxVersion: markdown-engine.validation@v2
+rules:
+  - id: log.date-heading
+    select:
+      target: heading
+      depth: 2
+    assert:
+      textFormat:
+        format: isoDate
+```
+
+The v1 profile above continues to emit the v1 validation-result shape. V2
+profiles emit syntax-versioned v2 result metadata with
+`evaluatedRuleCount` and `skippedRuleCount`; v2 rule results include `status`
+and `evaluation`. The CLI does not add a second discriminator for v2; consumers
+branch on
+`profile.syntaxVersion: "markdown-engine.validation@v2"`.
+
 Migration notes:
 
 - Consumers using fixed `validate(document, config)` rule families can continue
@@ -438,6 +767,11 @@ Migration notes:
 - Consumers parsing CLI validation output must handle the
   `DeclarativeValidationCliJsonResult` union. Profile-stage failures do not
   include `profile` or `evidence`.
+- Consumers opting into `markdown-engine.validation@v2` must handle rule
+  `status` values of `"passed"`, `"failed"`, and `"skipped"`, plus
+  `evaluatedRuleCount`, `skippedRuleCount`, grouped branch results, and nested
+  skipped-rule `when` diagnostics. Aggregate validity is still determined from
+  top-level diagnostics.
 - Consumers that compare evidence hashes must normalize expectations around
   resolved `documentVersion`, default rule severity, stable key order, and
   exclusion of only top-level `document.path` from `inputHash`.
@@ -501,6 +835,88 @@ rules:
         count: 1
 ```
 
+Conditional v2 grouped rule with applicability:
+
+```yaml
+syntaxVersion: markdown-engine.validation@v2
+rules:
+  - id: release.when.docs-ready
+    when:
+      select:
+        target: section
+        title: Release
+      assert:
+        exists: true
+    anyOf:
+      - label: contract-link
+        select:
+          target: link
+          section: Release
+          text: contract
+        assert:
+          exists: true
+      - label: contract-heading
+        select:
+          target: heading
+          text: Contract
+        assert:
+          exists: true
+```
+
+### OKF v0.1 Hard-Validation Profile Composition
+
+`markdown-engine` does not ship a built-in OKF validator. Consumers that want to
+validate OKF v0.1 hard conformance compose generic declarative-validation
+profiles and route documents to those profiles themselves. The caller owns
+bundle traversal, path classification, IO, and role selection before invoking
+`validateDocumentSet`.
+
+The packaged OKF proof under
+`fixtures/declarative-validation/examples/okf-v0.1/**` uses four generic
+profiles:
+
+| Caller-classified role | Example profile | Generic checks |
+| --- | --- | --- |
+| Concept document | `profiles/concept.yaml` | `frontmatterShape` requires parseable frontmatter with a non-empty string `type`. |
+| Bundle-root `index.md` | `profiles/root-index.yaml` | `frontmatterShape` accepts a non-empty string `okf_version` when root version frontmatter is present. |
+| Non-root `index.md` | `profiles/non-root-index.yaml` | `frontmatterShape` forbids frontmatter on directory index files. |
+| `log.md` | `profiles/log.yaml` | `textFormat` checks level-2 log headings as real `YYYY-MM-DD` dates. |
+
+Concept validation applies only to non-reserved concept documents. Reserved
+`index.md` and `log.md` files are not routed through the concept profile and do
+not fail merely because they lack concept `type` frontmatter. The bundle-root
+`index.md` may carry the OKF version exception `okf_version: "0.1"` through the
+root-index profile; non-root `index.md` files use the non-root index profile and
+forbid frontmatter. `log.md` is validated as a log with `textFormat`, not as a
+concept document.
+
+A caller-owned routing layer can classify entries by path and choose the
+matching profile before validation:
+
+```ts
+const entries = bundleMarkdownFiles.map((file) => {
+  const role = classifyOkfPath(file.path);
+
+  return {
+    path: file.path,
+    markdown: file.markdown,
+    profile: profilesByRole[role],
+    profilePath: profilePathsByRole[role],
+  };
+});
+
+const result = validateDocumentSet(entries, {
+  documentVersion: "1.0.0",
+  includeEvidence: true,
+});
+```
+
+This composition proves hard OKF conformance only. It does not add CLI
+traversal, an OKF adapter, runtime OKF semantics, directory watching, bundle
+discovery, link checking, unknown-type rejection, optional metadata quality
+checks, or rejection of missing optional `index.md` files. It also does not add
+engine-owned path classification.
+
 CLI invocation:
 
 ```sh
@@ -540,6 +956,11 @@ The v1 contract explicitly excludes:
 - operational-design-spec, AGENTS.md, TASK.md, or other domain-specific rule
   meaning in core engine code
 
+The admitted v2 Conditional V2 surface also excludes `documentVersion: "3.0.0"`,
+recursive grouped rules, branch-level `when`, profile-defined predicates,
+assertion-specific evidence payloads, a separate skipped-rule evidence channel,
+and a new CLI JSON discriminator.
+
 The CLI reads only the caller-specified local Markdown and profile files. The
 API owns no file traversal, daemon, database, browser runtime, network service,
 agent adapter, MCP transport, runtime lens, or persistent cache.
@@ -553,7 +974,8 @@ npm run docs:declarative-validation-contract
 npm run audit:declarative-validation-boundary
 ```
 
-The documentation gate checks this contract, README links, evidence files, and
-package script wiring. The boundary audit checks dependency drift, source-level
-runtime boundary patterns, unsupported regex-like and executable profile-key
-coverage, and declarative validation boundary evidence.
+The documentation gate checks this contract, README links, legacy contract and
+boundary evidence files, Conditional V2 EVD-6 reviewer notes, and package script
+wiring. The boundary audit checks dependency drift, source-level runtime
+boundary patterns, unsupported regex-like and executable profile-key coverage,
+and declarative validation boundary evidence.