@jasonbelmonti/markdown-engine 2.0.0 → 3.1.0

package/docs/contracts/api.md

@@ -1,10 +1,10 @@
 # Public API Contract
 
-Status: package 2.0.0, document contract 1.0.0
-Last updated: 2026-05-13
+Status: package 3.0.0, document contract 1.0.0
+Last updated: 2026-06-05
 
 This document defines the public `@jasonbelmonti/markdown-engine` package
-contract for the `2.0.0` package release. The serialized rich IR document
+contract for the `3.0.0` package release. The serialized rich IR document
 contract remains `documentVersion: "1.0.0"`. The stable public surface is the
 package export from `@jasonbelmonti/markdown-engine`, not internal adapter
 modules or raw parser output. The 1.0 rich IR design is tracked in
@@ -22,6 +22,7 @@ The package root exports the API functions, helpers, and types from `src/api/**`
 - `validateAnnotations(document, annotations)`
 - `parseValidationProfile(input, options?)`
 - `validateWithProfile(document, profile, options?)`
+- `validateDocumentSet(entries, options?)`
 
 The package root also exports the public result, document, diagnostic, config,
 and function types declared in `src/api/**`.
@@ -72,7 +73,7 @@ normalize(parsed: ParsedMarkdown, options?: NormalizeOptions): NormalizeResult
 ```
 
 `NormalizeOptions.documentVersion` selects the document contract version.
-Package 2.0 defaults omitted `documentVersion` to the rich IR
+Package 3.0 keeps omitted `documentVersion` defaulting to the rich IR
 `"1.0.0"` contract. The retained `0.1.0`-compatible path is `"0.0.0"` and must
 be requested explicitly.
 
@@ -227,7 +228,9 @@ validateWithProfile(
 
 `parseValidationProfile` accepts YAML text or JSON-safe profile objects. The
 top-level profile keys are `syntaxVersion`, `documentVersion`, and `rules`.
-`syntaxVersion` must be `"markdown-engine.validation@v1"`.
+`syntaxVersion` must be `"markdown-engine.validation@v1"` or
+`"markdown-engine.validation@v2"`; v2 admission is limited to the existing flat
+rule shape.
 `documentVersion` is optional; when provided it must be `"0.0.0"` or
 `"1.0.0"`. The parser preserves omission and does not inject a default into
 the parsed profile.
@@ -247,6 +250,64 @@ defaults, so an omitted `documentVersion` and an explicit matching
 `documentVersion` produce the same profile hash for the same document version
 and rules.
 
+## `validateDocumentSet`
+
+Signature:
+
+```ts
+validateDocumentSet(
+  entries: readonly ValidateDocumentSetEntry[],
+  options?: ValidateDocumentSetOptions,
+): ValidateDocumentSetResult
+```
+
+`validateDocumentSet` is a pure aggregate API for caller-supplied Markdown
+documents and caller-supplied validation profiles. Each entry contains:
+
+- `path`: caller-owned document path or stable identifier
+- `markdown`: Markdown text to parse and normalize
+- `profile`: YAML profile text, JSON-safe profile data, or parsed
+  `ValidationProfile`
+- `profilePath`: optional caller-owned profile path or stable identifier for
+  profile diagnostics
+
+The function processes entries in the supplied order and returns `entries` in
+that same order. It does not read directories, expand globs, watch files, write
+persistent state, add CLI behavior, classify OKF paths, or choose profiles for
+callers. Consumers own discovery, routing, and IO.
+
+For OKF-style bundles, `validateDocumentSet` stays a generic aggregation API.
+Callers must classify each path before calling the function and provide the
+profile for that caller-classified role. A non-reserved concept document can use
+a concept profile that requires `type` frontmatter, the bundle-root `index.md`
+can use a root-index profile that accepts the `okf_version: "0.1"` exception, a
+non-root `index.md` can use a no-frontmatter profile, and `log.md` can use a
+log profile that checks date headings.
+
+The API does not infer those roles from paths.
+
+`ValidateDocumentSetOptions` forwards supported document normalization and
+validation options:
+
+- `documentVersion`
+- `preserveSourceLocations`
+- `includeEvidence`
+
+Each `ValidateDocumentSetEntryResult` contains:
+
+- `path` and optional `profilePath`
+- `parseDiagnostics`
+- `normalizationDiagnostics`
+- `profileDiagnostics`
+- `validationDiagnostics`
+- aggregate entry `diagnostics`
+- `validationResult` when profile parsing succeeds without error-severity
+  diagnostics
+
+Profile-stage failures on one entry do not stop later entries from processing.
+The aggregate `valid` field is `false` when any aggregate diagnostic has
+severity `error`; otherwise it is `true`.
+
 ## `serialize`
 
 Signature:
@@ -258,6 +319,7 @@ serialize(
     | NormalizeResult
     | ValidationResult
     | DeclarativeValidationResult
+    | ValidateDocumentSetResult
     | EngineDocument
     | AnnotationValidationResult,
   options?: SerializeOptions,
@@ -309,7 +371,7 @@ code nodes with `kind: "fenced"`. Raw parser node objects are not public.
 
 ## 1.0 Contract
 
-The final 1.0 document contract is selected by default in package 2.0, remains
+The final 1.0 document contract is selected by default in package 3.0, remains
 available explicitly as `documentVersion: "1.0.0"`, and is checked with
 `compatibilityMode: "default"`.
 
@@ -536,8 +598,8 @@ serialization behavior.
 
 ### Compatibility And Migration
 
-The current package version is `2.0.0`. The serialized document contract
-version remains `"1.0.0"`. Package 2.0 selects that rich IR contract by
+The current package version is `3.0.0`. The serialized document contract
+version remains `"1.0.0"`. Package 3.0 selects that rich IR contract by
 default for `normalize(parsed)`; callers may also request it explicitly with
 `normalize(..., { documentVersion: "1.0.0" })`. Serialization gates check it
 with `compatibilityMode: "default"`.
@@ -550,7 +612,7 @@ compatibility from the absence of rich IR fields.
 Migration from the `0.1.0` document shape, or from pre-2.0 API callers that
 depended on implicit legacy normalization, requires consumers to:
 
-- use package 2.0's default `normalize(parsed)` rich IR output or request
+- use package 3.0's default `normalize(parsed)` rich IR output or request
   `documentVersion: "1.0.0"` during normalization;
 - read `target`, `sections`, `textSpans`, `tables`, `lists`, `links`,
   `linkReferences`, and `source` from the normalized document instead of
@@ -609,10 +671,10 @@ exit with code `2`. Validation success exits with code `0`; validation or
 normalization error diagnostics exit with code `1`. Validation JSON includes
 `profile`, `ruleResults`, `diagnostics`, and `evidence`.
 
-Semver classification: package 2.0 makes the rich IR contract the default API
-normalization output while retaining the document contract version
-`"1.0.0"`. This is breaking for API consumers that call `normalize(parsed)` and
-expect the legacy `0.0.0` document shape. Migration is to either consume the
+Semver classification: package 3.0 keeps the rich IR contract as the default
+API normalization output while retaining the document contract version
+`"1.0.0"`. The 2.0 migration remains applicable for API consumers that call
+`normalize(parsed)` and expect the legacy `0.0.0` document shape: consume the
 rich IR fields or pin `documentVersion: "0.0.0"` until the downstream consumer
 is ready. CLI consumers can still pin `--document-version 0.0.0` for explicit
 legacy output.
@@ -651,8 +713,10 @@ The `0.1.0` contract was review-gated by WP-2, MS-2, and MS-3 before first
 publication. From the published `0.1.0` baseline forward, changes to public API
 signatures, result fields, diagnostic schema, source-location semantics,
 validation config semantics, or serialized output shape require
-semantic-version classification. The planned 1.0 rich IR contract will update
-this API contract before 1.0 release approval.
+semantic-version classification. The 1.0 rich IR document contract is now the
+retained default document contract for package 3.0, and the explicit legacy
+`0.0.0` path remains the compatibility boundary for consumers that still need
+the first package-line output shape.
 
 The `@jasonbelmonti/markdown-engine` package boundary remains limited to
 parsing, normalization, deterministic validation, diagnostics, and