@jasonbelmonti/markdown-engine 3.1.1 → 3.3.0

package/docs/contracts/declarative-validation.md

@@ -1,8 +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, ID count-bound schema and
+Last updated: 2026-08-12
+Current v2 surface: flat-rule result/evidence shell, generic selector
+`selectionCount` bounds, document `sourceLength` schema and runtime
+measurement, 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
@@ -25,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,
@@ -63,8 +66,19 @@ validateDocumentSet(
   entries: readonly ValidateDocumentSetEntry[],
   options?: ValidateDocumentSetOptions,
 ): ValidateDocumentSetResult
+
+interface DeclarativeValidationOptions {
+  path?: string;
+  includeEvidence?: boolean;
+  sourceText?: string;
+}
 ```
 
+`sourceText` carries the complete original Markdown string to validation. It is
+required only when an evaluated v2 `sourceLength` assertion needs to measure
+the pre-normalization input; it does not become an enumerable
+`EngineDocument` field.
+
 Compiled declarative validation plans are internal. They are not exported from
 the package root, are not serialized in API or CLI results, and carry no semver
 stability guarantee.
@@ -87,8 +101,9 @@ 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
@@ -281,6 +296,10 @@ Supported assertion members are:
 ```ts
 interface DeclarativeAssertion {
   exists?: true;
+  selectionCount?: {
+    min?: number;
+    max?: number;
+  };
   sectionsRequired?: {
     headings: readonly string[];
     order?: "none" | "strict";
@@ -334,6 +353,10 @@ interface DeclarativeAssertion {
     min?: number;
     max?: number;
   };
+  sourceLength?: {
+    min?: number;
+    max?: number;
+  };
   textFormat?: {
     format: "isoDate";
   };
@@ -355,6 +378,7 @@ 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` |
 | `ids` | all supported selector targets |
@@ -364,6 +388,7 @@ Selector/assertion compatibility is part of the public contract:
 | `text` | all supported selector targets |
 | `textOccurrenceCount` | all supported selector targets |
 | `textLength` | all supported selector targets |
+| `sourceLength` | `document` |
 | `textFormat` | all supported selector targets |
 | `frontmatterRequired` | `document` |
 
@@ -374,6 +399,16 @@ 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.
+
 `sectionsRequired.order` defaults to `none`. `strict` checks that configured
 headings appear as an ordered subsequence in the normalized section tree
 flattened in source order.
@@ -442,6 +477,17 @@ 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, `sourceLength` must include `min`, `max`, or both with the same
+non-negative integer and ordered-range rules. It is compatible only with a
+`document` selector and evaluates the complete `sourceText` supplied to
+`validateWithProfile`, including frontmatter, Markdown syntax, whitespace, line
+endings, and surrogate pairs, using JavaScript string `.length` (UTF-16 code
+units). The CLI and `validateDocumentSet` supply the exact Markdown input they
+read. When an evaluated `sourceLength` assertion has no complete source
+context, validation fails closed with
+`profile.validation.sourceUnavailable`; normalized document text and source
+ranges are never used as fallbacks.
+
 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,
@@ -455,9 +501,10 @@ 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, and text-format assertions.
+`selectionCount` instead evaluates the empty selection as zero. Document-scoped
+required-section, required-frontmatter, and frontmatter-shape assertions
+evaluate against the document.
 
 ## Diagnostics
 
@@ -470,9 +517,12 @@ 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
+`ruleResults[].when.diagnostics`; they are not normally promoted into top-level
 `diagnostics`, so a skipped rule with a nested error-severity applicability
-diagnostic can still leave the aggregate `valid` value `true`.
+diagnostic can still leave the aggregate `valid` value `true`. The
+`profile.validation.sourceUnavailable` safety diagnostic is the exception: it
+is promoted with error severity so unavailable raw-source context cannot yield
+an unproven pass.
 
 | Code | Severity source | Emitted when |
 | --- | --- | --- |
@@ -486,7 +536,7 @@ diagnostic can still leave the aggregate `valid` value `true`.
 | `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 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. |
@@ -498,6 +548,7 @@ diagnostic can still leave the aggregate `valid` value `true`.
 | `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.sourceUnavailable` | `error` | An evaluated `sourceLength` assertion cannot access the complete original Markdown source. |
 | `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. |
@@ -599,6 +650,7 @@ interface DeclarativeValidationEvidence<
   profileHash: string;
   engineVersion: string;
   runtimeVersion: string;
+  sourceLength?: number;
   ruleResults: readonly RuleResult[];
   diagnostics: readonly MarkdownDiagnostic[];
 }
@@ -613,10 +665,18 @@ diagnostics array. Evidence does not serialize compiled rule plans, selector
 target records, assertion-specific ID count evidence, or assertion-specific
 table-column coverage evidence.
 
+When a v2 profile uses `sourceLength` and complete source context is available,
+evidence exposes the measured UTF-16 code-unit count as `sourceLength`.
+Profiles that do not use the assertion omit this field and preserve their
+existing evidence serialization.
+
 `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
-canonical input.
+canonical input. For a profile using `sourceLength`, the canonical input is an
+object containing that normalized document plus the exposed `sourceLength`
+measurement, so otherwise equivalent normalized documents with different raw
+source lengths produce different input hashes.
 
 `profileHash` is a lowercase hexadecimal SHA-256 digest of the stable JSON
 serialization of the resolved `ValidationProfile` after applying the resolved
@@ -628,8 +688,10 @@ the same profile hash for the same document version and rules.
 matches the package metadata version even though `documentVersion` remains
 `"1.0.0"`.
 
-Raw Markdown bytes, raw YAML bytes, YAML comments, caller file paths, and
-`includeEvidence` itself are not part of either evidence hash.
+Raw Markdown content, raw YAML bytes, YAML comments, caller file paths, and
+`includeEvidence` itself are not part of either evidence hash. Only the numeric
+raw-source length measurement is added to `inputHash`, and only for profiles
+that use `sourceLength`.
 
 ## CLI Behavior
 
@@ -750,6 +812,18 @@ rules:
         format: isoDate
 ```
 
+```yaml
+# v2 source budget: bounds the complete original Markdown input.
+syntaxVersion: markdown-engine.validation@v2
+rules:
+  - id: document.source-budget
+    select:
+      target: document
+    assert:
+      sourceLength:
+        max: 12000
+```
+
 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`
@@ -773,8 +847,9 @@ Migration notes:
   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`.
+  resolved `documentVersion`, default rule severity, stable key order,
+  exclusion of only top-level `document.path`, and conditional inclusion of the
+  numeric `sourceLength` measurement in `inputHash`.
 - Regex-like matching, JavaScript predicates, plugins, semantic scoring, and
   profile-specific rules belong outside this package unless a future contract
   explicitly expands the engine boundary.
@@ -863,6 +938,24 @@ 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
+```
+
 ### 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.1.1",
+  "version": "3.3.0",
   "description": "Deterministic Markdown parsing and validation engine package.",
   "license": "MIT",
   "type": "module",
@@ -49,8 +49,9 @@
     "build:cli-bundle": "node scripts/build-cli-bundle.mjs",
     "prepack": "npm run release:verify",
     "prepublishOnly": "npm run release:verify",
-    "release:verify": "npm run typecheck && npm test && node scripts/check-boundaries.mjs && npm run docs:rich-ir-contract && npm run docs:declarative-validation-contract && npm run audit:declarative-validation-boundary && npm run build && npm run build:cli:bundled && node scripts/prove-repeatability.mjs --runs 10 && npm run release:check-clean",
-    "release:check-clean": "git diff --check HEAD -- && git diff --exit-code HEAD --",
+    "release:verify": "npm run typecheck && npm test && node scripts/check-boundaries.mjs && npm run docs:rich-ir-contract && npm run docs:declarative-validation-contract && npm run audit:declarative-validation-boundary && npm run build && npm run build:cli:bundled && npm run release:verify:installer-pin && node scripts/prove-repeatability.mjs --runs 10 && npm run release:check-clean",
+    "release:verify:installer-pin": "node scripts/check-installer-pin.mjs",
+    "release:check-clean": "node scripts/check-release-clean.mjs",
     "snapshots:update:parser": "npm run build && vitest run tests/parser-fixtures.test.ts -u \"--exclude=.worktrees/**\"",
     "snapshots:update:rules": "npm run build && vitest run tests/rules.test.ts -u \"--exclude=.worktrees/**\"",
     "snapshots:update:rich-ir": "npm run build && vitest run tests/rich-ir-targets.test.ts tests/rich-ir-queries.test.ts tests/rich-ir-link-references.test.ts -u \"--exclude=.worktrees/**\"",
@@ -70,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-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-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/**\"",
@@ -80,6 +81,8 @@
     "docs:declarative-validation-contract": "node scripts/check-declarative-validation-contract-docs.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && vitest run \"--exclude=.worktrees/**\"",
+    "test:coverage": "npm run build && npm run build:cli:bundled && vitest run --coverage \"--exclude=.worktrees/**\"",
+    "test:coverage:ci": "npm run test:coverage",
     "test:snapshots": "npm run build && vitest run tests/parser-fixtures.test.ts tests/rules.test.ts tests/rich-ir-targets.test.ts tests/rich-ir-queries.test.ts tests/rich-ir-link-references.test.ts tests/serialization-repeatability.test.ts \"--exclude=.worktrees/**\""
   },
   "engines": {
@@ -87,10 +90,11 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.17",
+    "@vitest/coverage-v8": "^3.2.7",
     "cmark-gfm": "^0.9.0",
     "esbuild": "^0.27.7",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.3"
+    "vitest": "^3.2.7"
   },
   "dependencies": {
     "remark-gfm": "^4.0.1",

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

@@ -1,9 +1,9 @@
 #!/usr/bin/env sh
 set -eu
 
-VERSION="3.1.1"
+VERSION="3.3.0"
 PACKAGE="@jasonbelmonti/markdown-engine"
-EXPECTED_SHA256="8c7ff572765cbdc6c38b94de52d69709f583ee7b4d2b7e25ba6be8c92125addf"
+EXPECTED_SHA256="367455824fde63074afe896510fd2133690bb3c06222257e579e575d59105768"
 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}"