@jasonbelmonti/markdown-engine 3.3.0 → 3.5.0

package/docs/contracts/declarative-validation.md

@@ -1,10 +1,10 @@
 # Declarative Validation Contract
 
 Status: package 3.0.0, v1 profile syntax with v2 Conditional V2, document contract 1.0.0
-Last updated: 2026-08-12
+Last updated: 2026-08-15
 Current v2 surface: flat-rule result/evidence shell, generic selector
 `selectionCount` bounds, document `sourceLength` schema and runtime
-measurement, ID count-bound schema and
+measurement, exact normalized table-header `tableColumnsExact` assertions, 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
@@ -106,7 +106,8 @@ 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
+internal compiled-plan, and runtime evaluator layers, admits `tableColumnsExact`
+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.
@@ -236,7 +237,7 @@ 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.
+`tableColumnsExact`, `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`
@@ -307,6 +308,9 @@ interface DeclarativeAssertion {
   tableColumnsRequired?: {
     columns: readonly string[];
   };
+  tableColumnsExact?: {
+    columns: readonly string[];
+  };
   ids?: {
     prefix?: string;
     unique?: boolean;
@@ -339,6 +343,9 @@ interface DeclarativeAssertion {
       required?: true;
       valueType?: "string" | "number" | "boolean" | "array" | "object" | "null";
       nonEmpty?: true;
+      equals?: string;
+      nonBlank?: true;
+      forbidden?: true;
     }[];
   };
   text?: {
@@ -381,6 +388,7 @@ Selector/assertion compatibility is part of the public contract:
 | `selectionCount` | all supported selector targets |
 | `sectionsRequired` | `document` |
 | `tableColumnsRequired` | `table` |
+| `tableColumnsExact` | `table` |
 | `ids` | all supported selector targets |
 | `references` | `document` |
 | `tableColumnCoverage` | `document` |
@@ -409,6 +417,19 @@ result with `profile.validation.emptySelection`. Maximum-bound failures use the
 first excess selected target as source evidence when available. Minimum-bound
 failures at zero omit source location rather than fabricating one.
 
+For v2 profiles, `tableColumnsExact` requires a non-empty `columns` array of
+non-empty strings and is compatible only with a `table` selector. It compares
+the complete normalized header sequence from the selected `EngineTable` exactly:
+count, order, text, and duplicate occurrences must all match. Additional
+columns before, between, or after configured columns, and missing, reordered,
+renamed, or duplicated columns fail with
+`profile.validation.assertionFailed`. The deterministic diagnostic includes the
+expected and actual header sequences. When an actual header first mismatches or
+is excess, its header-cell source range is attached when available; otherwise
+the normal selected-table source evidence is retained. This assertion does not
+change the ordered-subsequence behavior of `tableColumnsRequired` or table
+selector `header` / `tableHeader` matching.
+
 `sectionsRequired.order` defaults to `none`. `strict` checks that configured
 headings appear as an ordered subsequence in the normalized section tree
 flattened in source order.
@@ -446,12 +467,17 @@ 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
+constraint: `required: true`, `valueType`, `nonEmpty: true`, `equals`,
+`nonBlank: true`, or `forbidden: 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`.
+`nonEmpty: true`, `equals`, and `nonBlank: true` are string predicates; when
+any is combined with `valueType`, `valueType` must be `"string"`. `equals`
+accepts any string, including the empty string, and compares it exactly.
+`nonBlank: true` requires a string whose JavaScript `trim()` result is non-empty.
+`forbidden: true` requires the named field to be absent and cannot be combined
+with `required`, `valueType`, `nonEmpty`, `equals`, or `nonBlank`.
+`presence: "forbidden"` cannot be combined with `fields`.
 
 Runtime evaluation treats frontmatter as present when
 `document.frontmatter !== undefined`. `presence: "required"` fails absent
@@ -468,6 +494,16 @@ 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.
+`equals` compares present strings exactly without coercion and emits
+`profile.validation.frontmatterFieldValueMismatch` on mismatch. `nonBlank: true`
+uses JavaScript `trim()` without coercion and emits
+`profile.validation.frontmatterFieldBlank` when its field is not a non-blank
+string. `forbidden: true` emits `profile.validation.frontmatterFieldForbidden`
+when the named field is present, regardless of value. When `valueType: "string"`
+is combined with `equals` or `nonBlank`, a non-string value emits only
+`profile.validation.frontmatterFieldTypeMismatch` rather than an additional
+string-predicate diagnostic. Diagnostic messages do not include frontmatter
+values.
 
 `text` must include `contains` or a non-empty `excludes` array.
 `textOccurrenceCount.count` is a finite number and counts non-overlapping
@@ -501,7 +537,8 @@ 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, text-length, and text-format assertions.
+table, ID, reference, text, occurrence, text-length, text-format, and
+tableColumnsExact assertions.
 `selectionCount` instead evaluates the empty selection as zero. Document-scoped
 required-section, required-frontmatter, and frontmatter-shape assertions
 evaluate against the document.
@@ -536,12 +573,15 @@ an unproven pass.
 | `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 selector-count bound failures, missing table columns, exact occurrence-count mismatches, text-length bound failures, and text-format `isoDate` failures. |
+| `profile.validation.assertionFailed` | Rule severity | A supported assertion evaluates and fails without a more specific diagnostic code, including selector-count bound failures, missing table columns, exact table-header mismatches, 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.frontmatterFieldBlank` | Rule severity | A frontmatter field configured with `nonBlank: true` is not a non-blank string. |
 | `profile.validation.frontmatterFieldEmpty` | Rule severity | A frontmatter field configured with `nonEmpty: true` is not a non-empty string. |
+| `profile.validation.frontmatterFieldForbidden` | Rule severity | A frontmatter field configured with `forbidden: true` is present. |
 | `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.frontmatterFieldValueMismatch` | Rule severity | A frontmatter field configured with `equals` does not exactly match the configured string 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`. |
@@ -956,6 +996,26 @@ rules:
         max: 1
 ```
 
+V2 exact table-column profile:
+
+```yaml
+syntaxVersion: markdown-engine.validation@v2
+rules:
+  - id: task-control.columns
+    select:
+      target: table
+    assert:
+      tableColumnsExact:
+        columns:
+          - Contract state
+          - Execution route
+          - State rationale
+```
+
+The assertion compares the complete normalized header sequence. It is stricter
+than `tableColumnsRequired`, which continues to accept ordered-subsequence
+matches with unrelated columns before, between, or after required names.
+
 ### OKF v0.1 Hard-Validation Profile Composition
 
 `markdown-engine` does not ship a built-in OKF validator. Consumers that want to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonbelmonti/markdown-engine",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Deterministic Markdown parsing and validation engine package.",
   "license": "MIT",
   "type": "module",
@@ -71,7 +71,7 @@
     "test:validation:profile": "npm run build && vitest run tests/declarative-validation-profile.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:compiler": "npm run build && vitest run tests/declarative-validation-compiler.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:selectors": "npm run build && vitest run tests/declarative-validation-selectors.test.ts \"--exclude=.worktrees/**\"",
-    "test:validation:assertions": "npm run build && vitest run tests/declarative-validation-assertions.test.ts tests/declarative-validation-frontmatter-shape-assertions.test.ts tests/declarative-validation-table-column-coverage-fixtures.test.ts tests/declarative-validation-source-assertion-coverage.test.ts tests/declarative-validation-source-length.test.ts tests/declarative-validation-selection-count.test.ts tests/declarative-validation-normalized-source-ranges.test.ts tests/declarative-validation-grouped-rules-fixtures.test.ts tests/declarative-validation-when-skipped-rules-fixtures.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:assertions": "npm run build && vitest run tests/declarative-validation-assertions.test.ts tests/declarative-validation-frontmatter-shape-assertions.test.ts tests/declarative-validation-table-column-coverage-fixtures.test.ts tests/declarative-validation-table-columns-exact.test.ts tests/declarative-validation-source-assertion-coverage.test.ts tests/declarative-validation-source-length.test.ts tests/declarative-validation-selection-count.test.ts tests/declarative-validation-normalized-source-ranges.test.ts tests/declarative-validation-grouped-rules-fixtures.test.ts tests/declarative-validation-when-skipped-rules-fixtures.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:diagnostics": "npm run build && vitest run tests/declarative-validation-diagnostics.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:cli": "npm run build && vitest run tests/declarative-validation-cli.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:examples": "npm run build && vitest run tests/declarative-validation-examples.test.ts \"--exclude=.worktrees/**\"",

package/scripts/install-markdown-engine-cli.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env sh
 set -eu
 
-VERSION="3.3.0"
+VERSION="3.5.0"
 PACKAGE="@jasonbelmonti/markdown-engine"
-EXPECTED_SHA256="367455824fde63074afe896510fd2133690bb3c06222257e579e575d59105768"
+EXPECTED_SHA256="4a4e9ae7d9ff4797c96a7483555bcba7cbec5852d330c6c50dc0ef8fb2e5d933"
 DEFAULT_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
 MARKDOWN_ENGINE_HOME="${MARKDOWN_ENGINE_HOME:-$DEFAULT_DATA_HOME/markdown-engine}"
 MARKDOWN_ENGINE_BIN_DIR="${MARKDOWN_ENGINE_BIN_DIR:-$HOME/.local/bin}"