@jasonbelmonti/markdown-engine 3.2.0 → 3.4.0

package/docs/contracts/declarative-validation.md

@@ -1,9 +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-06-15
-Current v2 surface: flat-rule result/evidence shell, document `sourceLength`
-schema and runtime measurement, ID count-bound schema and
+Last updated: 2026-08-15
+Current v2 surface: flat-rule result/evidence shell, generic selector
+`selectionCount` bounds, document `sourceLength` schema and runtime
+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
@@ -26,7 +27,8 @@ rich IR document contract, while the profile admission path recognizes
 `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
+from v1 output, plus generic selector `selectionCount` bounds, 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,
@@ -99,11 +101,13 @@ 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
+admits `selectionCount` and 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
+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.
@@ -233,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`
@@ -293,6 +297,10 @@ Supported assertion members are:
 ```ts
 interface DeclarativeAssertion {
   exists?: true;
+  selectionCount?: {
+    min?: number;
+    max?: number;
+  };
   sectionsRequired?: {
     headings: readonly string[];
     order?: "none" | "strict";
@@ -300,6 +308,9 @@ interface DeclarativeAssertion {
   tableColumnsRequired?: {
     columns: readonly string[];
   };
+  tableColumnsExact?: {
+    columns: readonly string[];
+  };
   ids?: {
     prefix?: string;
     unique?: boolean;
@@ -371,8 +382,10 @@ Selector/assertion compatibility is part of the public contract:
 | Assertion | Compatible selector targets |
 | --- | --- |
 | `exists` | all supported selector targets |
+| `selectionCount` | all supported selector targets |
 | `sectionsRequired` | `document` |
 | `tableColumnsRequired` | `table` |
+| `tableColumnsExact` | `table` |
 | `ids` | all supported selector targets |
 | `references` | `document` |
 | `tableColumnCoverage` | `document` |
@@ -391,6 +404,29 @@ Incompatible supported selector/assertion pairs emit
 target and fails with `profile.validation.emptySelection` when the selector
 resolves zero targets.
 
+For v2 profiles, `selectionCount` must include `min`, `max`, or both. Bounds
+are inclusive non-negative integers, and `min` must be less than or equal to
+`max` when both are present. It evaluates the number of targets resolved by the
+rule selector and is compatible with every supported selector target. An empty
+selection is count zero, so `max: 0` passes and `min: 1` fails with
+`profile.validation.assertionFailed`; `selectionCount` does not replace its
+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.
@@ -483,9 +519,11 @@ 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. Document-scoped required-section, required-frontmatter, and
-frontmatter-shape assertions evaluate against the document.
+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.
 
 ## Diagnostics
 
@@ -517,7 +555,7 @@ 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 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.frontmatterFieldEmpty` | Rule severity | A frontmatter field configured with `nonEmpty: true` is not a non-empty string. |
@@ -919,6 +957,44 @@ rules:
           exists: true
 ```
 
+V2 selector cardinality profile:
+
+```yaml
+syntaxVersion: markdown-engine.validation@v2
+rules:
+  - id: actions.table.exactly-one
+    select:
+      target: table
+      section: Execution Actions
+      header:
+        - Step ID
+        - Action
+    assert:
+      selectionCount:
+        min: 1
+        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.2.0",
+  "version": "3.4.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-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.2.0"
+VERSION="3.4.0"
 PACKAGE="@jasonbelmonti/markdown-engine"
-EXPECTED_SHA256="5033d08160fcd3f44b11498dc29d01db73d7aff2a55eb3257fd9a1c14e29c3f6"
+EXPECTED_SHA256="41225925904c038c05392b19e7203bd723d1cbaaa47b48d96648fb0275d3d05b"
 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}"