okf-core 0.4.0.0 → 0.5.0.0

raw patch · 72 files changed

+14770/−5539 lines, 72 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• CHANGELOG.md +238/−0
• dhall/FieldFormat.dhall +13/−1
• dhall/FieldRule.dhall +19/−0
• dhall/NestedFieldRule.dhall +16/−3
• dhall/PathReferenceRule.dhall +20/−0
• dhall/Profile.dhall +8/−0
• dhall/defaults/FieldRule.dhall +4/−0
• dhall/defaults/NestedFieldRule.dhall +3/−0
• dhall/defaults/PathReferenceRule.dhall +13/−0
• dhall/defaults/Profile.dhall +1/−0
• dhall/mk/FieldRule.dhall +32/−0
• dhall/mk/NestedFieldRule.dhall +25/−0
• dhall/package.dhall +2/−0
• okf-core.cabal +12/−1
• src/Okf/Actor.hs +68/−0
• src/Okf/Bundle.hs +212/−4
• src/Okf/Document.hs +697/−8
• src/Okf/Graph.hs +20/−25
• src/Okf/Index.hs +239/−17
• src/Okf/Log.hs +2/−1
• src/Okf/Markdown.hs +255/−0
• src/Okf/Path.hs +141/−0
• src/Okf/Profile.hs +3903/−2480
• src/Okf/Profile/Documentation.hs +586/−0
• src/Okf/Trust.hs +120/−0
• src/Okf/Validation.hs +548/−15
• test/Main.hs +6269/−2976
• test/fixtures/attested-computation/computations/both-computations.md +27/−0
• test/fixtures/attested-computation/computations/churn.md +31/−0
• test/fixtures/attested-computation/computations/margin.md +23/−0
• test/fixtures/attested-computation/computations/no-computation.md +17/−0
• test/fixtures/attested-computation/computations/revenue.md +35/−0
• test/fixtures/attested-computation/computations/two-blocks.md +35/−0
• test/fixtures/attested-computation/index.md +13/−0
• test/fixtures/attested-computation/metrics/revenue.md +19/−0
• test/fixtures/attested-computation/references/attesters/revenue.py +16/−0
• test/fixtures/attested-computation/references/queries/revenue.sql +3/−0
• test/fixtures/attested-computation/references/skills/run-on-bq.md +22/−0
• test/fixtures/dangling-frontmatter-path/computations/index.md +3/−0
• test/fixtures/dangling-frontmatter-path/computations/spec-spelling.md +26/−0
• test/fixtures/dangling-frontmatter-path/dangling.md +14/−0
• test/fixtures/dangling-frontmatter-path/external.md +13/−0
• test/fixtures/dangling-frontmatter-path/index.md +10/−0
• test/fixtures/dangling-frontmatter-path/non-markdown.md +15/−0
• test/fixtures/dangling-frontmatter-path/references/attesters/revenue.py +1/−0
• test/fixtures/profiles/attested-computation-house.dhall +131/−0
• test/fixtures/profiles/cardinality.dhall +1/−0
• test/fixtures/profiles/closed-fields.dhall +1/−0
• test/fixtures/profiles/conditional-fields-ep2.dhall +13/−1
• test/fixtures/profiles/decisions.dhall +1/−0
• test/fixtures/profiles/document-references-ep3.dhall +13/−1
• test/fixtures/profiles/document-references-invalid.dhall +1/−0
• test/fixtures/profiles/document-references.dhall +1/−0
• test/fixtures/profiles/formats-ep4.dhall +13/−1
• test/fixtures/profiles/formats-mp8-ep2.dhall +182/−0
• test/fixtures/profiles/formats.dhall +1/−0
• test/fixtures/profiles/nested-reviews-ep1.dhall +13/−1
• test/fixtures/profiles/nested-reviews.dhall +1/−0
• test/fixtures/profiles/object-fields-mp8-ep1.dhall +172/−0
• test/fixtures/profiles/path-references-mp8-ep3.dhall +198/−0
• test/fixtures/profiles/postgresql.dhall +1/−0
• test/fixtures/profiles/pre-bundle-version.dhall +189/−0
• test/fixtures/profiles/type-frontmatter.dhall +1/−0
• test/fixtures/v01-legacy-bundle/index.md +10/−0
• test/fixtures/v01-legacy-bundle/log.md +4/−0
• test/fixtures/v01-legacy-bundle/tables/index.md +3/−0
• test/fixtures/v01-legacy-bundle/tables/orders.md +15/−0
• test/fixtures/valid-bundle/datasets/sales.md +3/−1
• test/fixtures/valid-bundle/index.md +4/−0
• test/fixtures/valid-bundle/references/source-system.md +3/−1
• test/fixtures/valid-bundle/tables/customers.md +3/−1
• test/fixtures/valid-bundle/tables/orders.md +3/−1

@@ -7,6 +7,244 @@  ## [Unreleased] +## [0.5.0.0] - 2026-08-01++### Added++- **OKF v0.2 core semantics.** okf now tracks version 0.2 of the Open Knowledge+  Format. Every family below is optional; `type` remains the only key a concept+  must have, and no bundle is ever rejected for omitting one.+- `Okf.Actor`: the specification §7 actor convention, with `parseActor` (total,+  never fails), `renderActor` (its exact inverse), and `isHumanActor`, which is+  the single test separating the machine-confirmed trust tier from+  human-reviewed. Four fields carry an actor: `generated.by`, `verified[].by`,+  and `sources[].author`.+- The trust family (§5.2): `Generated`/`readGenerated`/`setGenerated` for who or+  what produced a concept's content and when, and+  `Verification`/`readVerified`/`setVerified` for independent confirmation.+  `readVerified` accepts a bare mapping as a one-element list, as §5.2 requires.+- The lifecycle family (§5.4, §5.5): `Status`/`readStatus`/`renderStatus`/+  `setStatus`, where an absent key means `stable`, and `readStaleAfter`/+  `setStaleAfter`.+- The provenance family (§5.1): `Source`/`readSources`/`setSources` with the+  credibility signals `author`, `usage_count`, and `last_modified`, plus+  `UsageWindow`/`readUsageWindow`/`setUsageWindow` and `effectiveUsageWindow`,+  which resolves an entry's own window against the document-scope one.+  `usage_count` is read only from a YAML integer; a numeric string is not+  coerced.+- `Okf.Trust`: `trustTier`, `renderTrustTier`, `latestVerification`,+  `staleness`, and `renderStaleness`. Everything here is derived on read and+  never stored, and no function in `okf-core` reads the clock — `staleness`+  takes the current day as an argument. See+  `docs/adr/8-derived-not-stored-trust-and-credibility.md`.+- `Okf.Bundle.Concept` projects six more typed fields from frontmatter —+  `generated`, `verified`, `status`, `staleAfter`, `sources`, `usageWindow` —+  with matching accessors. Every projection restates frontmatter; none is a+  derivation.+- The bundle-root version declaration of §12: `OkfVersion`,+  `VersionDeclaration`, `readBundleVersion`, `parseOkfVersion`,+  `renderOkfVersion`, `supportedOkfVersion`, and `renderRootIndex` in+  `Okf.Index`. `Okf.Validation.versionGate` is the one place that decides what a+  declared version implies, and `gateDeclaresAtLeast` is the only question a+  check asks of it. An unknown minor within a known major is read as the highest+  known version; an unknown major is read permissively. Neither is ever a refusal.+  See `docs/adr/10-okf-version-declaration-and-best-effort-reading.md`.+- `Okf.Markdown`, with one shared `markdownOptions` list, `extractFootnoteLabels`,+  and `footnoteLabelsUsed`. All three `commonmarkToNode` call sites now route+  through it and Markdown footnotes are enabled. See+  `docs/adr/9-one-markdown-parse-configuration-and-source-scanned-authoring-checks.md`.+- `okf-core/test/fixtures/v01-legacy-bundle`, a deliberately unmigrated v0.1+  bundle that keeps the legacy fallback under test. Do not migrate it.+- **Object rules on profile field rules.** `FieldRule` gains+  `objectFields :: Maybe NestedRules`, describing the record that *is* a key's+  value, as distinct from `elementFields`, which describes the record inside each+  element of a list. Both take the same `NestedRules` value and their members are+  checked identically; only the reported `FieldPath` differs (`generated.by`+  against `reviews[0].kind`). Declaring both accepts either spelling, which is how+  a profile describes the OKF v0.2 `verified` key. `NestedFieldRule` gains+  neither member, so the descriptor stays depth-bounded.+  `EffectiveFieldRule` gains the `fieldRuleObjectFields` accessor, and generated+  profile documentation gains an `- Object fields:` bullet. Declaring+  `objectFields` and no explicit cardinality refines the rule to the new+  compiled-only `Cardinality` constructor `Object`; pairing it with an explicit+  `Scalar` or `List` is the new definition error+  `ObjectFieldsRequireObjectShape`. See+  `docs/adr/11-growing-the-profile-descriptor-language.md`.+- `okf-core/test/fixtures/profiles/object-fields-mp8-ep1.dhall`, the frozen+  descriptor generation from immediately before `objectFields` existed. Do not+  edit it.+- **The OKF v0.2 `Attested Computation` concept type (§10).** A concept of that+  exact type carries a sanctioned way to compute a value, so a consumer can+  confirm a number came from running the blessed computation rather than from an+  agent improvising its own query. `Okf.Document` reads the five contract keys —+  `runtime`, `parameters`, `computation`, `executor`, `attester` — with+  `Parameter`, `Executor`, `Attester`, and `attestedComputationType`, the exact+  case-sensitive type string. All five joined `coreFrontmatterFieldOrder` and+  `fieldsIntroducedInV02`, between `status` and `generated`, which is §10.2's own+  worked-example order, so serialization round-trips a §10.2 concept unchanged.+  `Okf.Bundle` projects the lot onto `Concept`.+- The body half of §10.3: `Okf.Markdown.computationBlocks` finds the code blocks+  under a `# Computation` heading, bounded at the next heading of the same or+  shallower level, and accepts both the fenced spelling §10.3's prose names and+  the indented one §10.2's own example writes. `Okf.Document.ComputationSource`+  and `readComputationSources` restate what a document offers — file before+  inline — and `Okf.Bundle.conceptComputationSources` projects it. Every one of+  these is type-agnostic and never reports; scoping to the type is+  `Okf.Validation`'s job.+- Four strict-mode `ValidationError` constructors for that type and no other:+  `AttestedComputationMissingRuntime` for §10.2's one REQUIRED field, and+  `AttestedComputationHasNoComputation`, `AttestedComputationHasBothComputations`,+  and `AttestedComputationHasManyBlocks Int` for the three ways §10.3's+  exactly-one rule breaks. Strict-only, per+  `docs/adr/7-okf-v0-1-legacy-fallback-policy.md`: §11's conformance list reaches+  none of them and separately forbids rejecting a bundle for an unknown `type`,+  so "REQUIRED for this type" binds the producer and does not license a consumer+  to refuse.+- **Path-valued frontmatter fields are resolved against the bundle** (§6.2), a+  gap that predates attested computations — nothing in okf had ever looked at a+  path sitting in a frontmatter value. `Okf.Path` gains existence checking, and+  `Okf.Validation` reports `DanglingFrontmatterPath` under `StrictAuthoring` for+  `resource`, `computation`, `executor.resource`, and `attester.resource`. A+  relative path that would have resolved from the bundle root is told the+  leading-slash spelling to write instead. `sources[].resource` is deliberately+  excluded: §5.1 sanctions a scope descriptor there, so path-checking it would+  report correct bundles as broken. See+  `docs/adr/12-frontmatter-path-resolution.md`.+- `Okf.Profile.validateProfileWith` takes a `BundleInventory`, so a profile+  `path` rule resolves against every file in the bundle rather than only `.md`+  concepts — which is what §6.3's own `references/attesters/revenue.py` example+  needs. `validateProfile` is defined in terms of it and keeps its exact meaning:+  a caller that supplies no inventory has not looked, and okf reports nothing it+  did not check. See `docs/adr/13-the-references-convention-and-non-markdown-files.md`.+- `Okf.Index` lists a directory's non-Markdown files under a `# Files` heading,+  so a `references/attesters/` directory holding only `.py` files no longer+  generates a one-byte `index.md`.+- `okf-core/test/fixtures/attested-computation/`, a bundle carrying one complete+  contract, one of each §10.3 failure, one `Metric` that must never be mistaken+  for a computation, and one concept that is core-clean and deviates only from a+  house profile. `okf-core/test/fixtures/profiles/attested-computation-house.dhall`+  is that house profile, and is the descriptor `docs/user/profiles.md` documents.+- `Okf.Profile.Documentation.defaultDocumentationActor`, the actor+  `defaultDocumentationOptions` names as the producer of a generated+  documentation bundle: `ProcessActor "okf-profile-document"`. Deliberately+  version-free, so generated output stays byte-identical across okf releases.+- A profile may require its bundle to declare an OKF version.+  `ProfileSpec.requireBundleVersion` holds a minimum as `Just "0.2"`, and the new+  `Okf.Profile.validateProfileVersion` reports an undeclared, older, or+  unparseable declaration as `RequiredBundleVersionUnmet`. Specification §12+  makes the declaration a MAY, so `validateBundle` still never asks for one; this+  is the house-convention half, inert until a profile author writes the field.+  `compiledProfileRequiredBundleVersion` reads the parsed minimum off a compiled+  profile. See+  `docs/adr/10-okf-version-declaration-and-best-effort-reading.md`.+- `validateProfileVersion` is a new entry point rather than a parameter on+  `validateProfile` or `validateProfileWith`, whose signatures are unchanged: the+  check consults no concepts, and adding a parameter would break every caller.+- The generated profile documentation bundle gains a `Required bundle version`+  bullet in its `## Settings` list, so a profile setting cannot be a silent hole+  in its own documentation. Regenerating a committed documentation bundle+  produces that one added line.++### Changed++- **Breaking for exhaustive consumers, from the attested computation work.**+  Four changes, listed together because a consumer moving its okf pin meets them+  as one surface. `Okf.Validation.validateBundle` takes a required+  `BundleInventory` before its list of concepts — required rather than defaulted,+  so no caller can pass an empty inventory and have every path report as+  dangling. `BundleValidationError` gains `DanglingFrontmatterPath ConceptId Text+  FilePath (Maybe FilePath)`. `ValidationError` gains the four+  `AttestedComputation*` constructors listed above. And `Okf.Index.renderIndex`+  takes two further parameters, for the non-Markdown files in a directory.+  The arity change on `validateBundle` is the one that breaks a caller outright;+  the constructor additions break only an exhaustive `case`. Mori+  (`mori://shinzui/mori`) matches `ProfileViolation` and not `ValidationError` or+  `BundleValidationError` as of 2026-08-01, so the constructors do not reach it,+  but its call to `validateBundle` does — check before moving the pin rather than+  assuming, since that is a position on a date and not a guarantee.+  `Okf.Profile.validateProfile` is unchanged in signature and meaning.+- **Breaking for exhaustive consumers.** `Cardinality` gains a fourth+  constructor, `Object`, and `ProfileDefinitionError` gains+  `ObjectFieldsRequireObjectShape`. The `Cardinality` addition is the wider of+  the two: that type appears in `ConflictingCardinality`,+  `ElementFieldsRequireList`, `ConditionFieldNotScalar`, and+  `CardinalityMismatch`, so a consumer that renders a cardinality needs a new+  case even if it declares no object rules. `Object` is deliberately unreachable+  from Dhall — the published union in `okf-core/dhall/Cardinality.dhall` keeps+  exactly its three alternatives — so no pinned descriptor changes type. No+  `ProfileViolation` constructor was added.+- Adding `objectFields` to the closed Dhall `FieldRule` record is a schema+  event. The complete optional-presence generation is frozen before it and+  upgrades with `objectFields = None`, so descriptors written with record+  completion or the `mk` constructors are unaffected; a descriptor that annotates+  itself against okf's current schema by relative path must add the field, since+  Dhall rejects the annotation before any fallback decoder runs.+- A missing member of a nested record now carries the member's `description`+  prose in parentheses, as a missing top-level key already did. This applies to+  list elements as well as object members, and emits nothing where a member+  declares no description.+- **Breaking for exhaustive consumers.** `validateBundle` takes a+  `VersionDeclaration` between the profile and the concepts:+  `ValidationProfile -> VersionDeclaration -> [Concept] -> [BundleValidationError]`.+  Passing `VersionUndeclared` reproduces the previous behaviour exactly.+  `ValidationError` gains `MissingGeneratedField`, `GeneratedMustHaveActor`,+  `SourceMissingResource`, `DuplicateSourceId`, `FootnoteLabelNotInSources`,+  `SourceIdNotCited`, and `LegacyFieldInDeclaredV2`; `BundleValidationError`+  gains `BundleVersionUnparseable` and `BundleVersionNotUnderstood`. Every new+  diagnostic is `StrictAuthoring` only.+- **Strict validation asks for `generated` rather than `timestamp`**, falling+  back to a legacy `timestamp` when `generated` is absent, so nothing that+  passed before fails now. The message for a concept with neither changes from+  `missing recommended field: timestamp` to+  `missing generated field (or legacy timestamp)`. The fallback is silent in an+  undeclared bundle and reported in one that declares `okf_version: "0.2"`; see+  `docs/adr/7-okf-v0-1-legacy-fallback-policy.md`.+- **`logStaleness` reads `generated.at` first**, falling back to `timestamp`. A+  v0.2 concept with no `timestamp` at all is staleness-checked for the first+  time.+- `coreFrontmatterFieldOrder` gains all six v0.2 concept keys, so re-serializing+  a document orders them deterministically and a closed profile+  (`allowUnknownFields = False`) permits them without redeclaring. `timestamp`+  moved to the end of that order, which reorders it once in any document a+  producer re-serializes.+- Markdown bodies parse with footnotes enabled. This also fixes a bug: a+  single-token footnote definition such as `[^src]: doc.md` previously parsed as+  a link reference definition, producing a phantom dangling link.+- `setTimestamp`, `OkfCommon`'s `commonTimestamp`, and reading a v0.1+  `timestamp` are all retained. Writing v0.1 on purpose stays supported.+- `Okf.Profile.Documentation.DocumentationOptions` gains a `generated ::+  Maybe Generated` field carrying the OKF v0.2 `generated` family written on+  every generated document, and `defaultDocumentationOptions` now supplies one.+  `Nothing` omits the key. Generation still reads no clock: `generatedAt` is+  caller-supplied and absent by default.+- **Breaking for record-literal callers.** A consumer that constructs+  `DocumentationOptions` as a record literal rather than by overriding+  `defaultDocumentationOptions` must add the new field. The module Haddock has+  always directed callers to start from `defaultDocumentationOptions` for+  exactly this reason; a call site that does so is unaffected.+- **Breaking for exhaustive matchers and record-literal callers**, from+  `requireBundleVersion`. `ProfileSpec` gains a field, so a consumer building one+  as a record literal must add it. `ProfileViolation` gains+  `RequiredBundleVersionUnmet` — the first violation that carries no `ConceptId`,+  so a consumer grouping violations by concept needs a case for it — and+  `ProfileDefinitionError` gains `InvalidRequiredBundleVersion`. Handle all three+  before moving an okf pin. `okf profile show --json` gains a+  `requireBundleVersion` key for the same reason.+- The published Dhall schema `okf-core/dhall/Profile.dhall` gains+  `requireBundleVersion : Optional Text`, defaulted to `None Text` in+  `okf-core/dhall/defaults/Profile.dhall`. A descriptor written as+  `Profile::{ … }` is unaffected; one written as a bare record literal annotated+  `: Profile` must add the member, and one pinned at an earlier release keeps+  decoding through a new frozen generation+  (`okf-core/test/fixtures/profiles/pre-bundle-version.dhall`).++### Fixed++- The sdist ships `test/fixtures/**/*.sql`. The `attested-computation` fixture+  points a `computation` field at a `.sql` file, so without it `cabal test` on+  the released tarball reported that path as dangling — a failure only someone+  building from Hackage with tests enabled would ever have seen.+ ## [0.4.0.0] - 2026-07-30  ### Added

@@ -1,7 +1,19 @@---| Named textual formats available to profile field rules.+--| Named value formats available to profile field rules.+--+-- The first five constrain text. `Actor` and `HumanActor` constrain text against+-- the OKF v0.2 actor convention (specification §7): `<producer>/<version>`,+-- `human:<id>`, or `process:<id>`, with `HumanActor` accepting only the second.+-- `Integer`, `NonNegativeInteger`, and `Boolean` constrain a value that is not+-- text at all, and declaring one of them refines an unspecified cardinality to+-- `Scalar`. < Rfc3339Utc | Date | Uri | UriWithScheme : Text | DocumentHandle : Text+| Actor+| HumanActor+| Integer+| NonNegativeInteger+| Boolean >

@@ -8,6 +8,21 @@ -- `allowedValues = []` leaves textual values unconstrained. -- `cardinality = Cardinality.Any` preserves the legacy scalar-or-list presence -- behavior.+--+-- `elementFields` and `objectFields` are a pair and describe two different+-- shapes. `elementFields` describes the record inside *each element of a list*,+-- so `reviews: [{kind: human}, …]` is constrained with `elementFields`.+-- `objectFields` describes the record that *is* the value, so+-- `generated: {by: …, at: …}` is constrained with `objectFields`. Declaring both+-- means either spelling is accepted and both are checked against the same member+-- rules, which is how a profile describes the OKF v0.2 `verified` key: the+-- specification permits it as a list of mappings or as one bare mapping, and+-- requires a consumer to treat the bare mapping as a one-element list.+--+-- Declaring `objectFields` with no explicit cardinality means the key must be a+-- mapping. Declaring it alongside `cardinality = Cardinality.Scalar` or+-- `Cardinality.List` is a profile definition error, because a mapping is+-- neither. let Cardinality = ./Cardinality.dhall  let FieldFormat = ./FieldFormat.dhall@@ -18,12 +33,16 @@  let HandleReferenceRule = ./HandleReferenceRule.dhall +let PathReferenceRule = ./PathReferenceRule.dhall+ in  { field : Text     , description : Optional Text     , allowedValues : List Text     , cardinality : Cardinality     , format : Optional FieldFormat     , elementFields : Optional NestedRules+    , objectFields : Optional NestedRules     , reference : Optional HandleReferenceRule+    , path : Optional PathReferenceRule     , when : Optional FieldCondition     }

@@ -1,17 +1,30 @@---| Canonical schema for one field inside a list element record.+--| Canonical schema for one field inside a list element record, or inside the+-- mapping that is an object-valued field. ----- This deliberately omits `elementFields`, so profile schemas are bounded to--- one list of flat records rather than recursively nested objects.+-- This deliberately omits `elementFields` and `objectFields`, so profile schemas+-- are bounded to one level of flat records rather than recursively nested+-- objects.+--+-- It does carry `path`, because `sources[].resource` — the motivating+-- path-valued field of OKF v0.2 specification §6.2 — lives inside a list element+-- record and is unreachable from a top-level rule. It deliberately does not+-- carry `reference`: no v0.2 field names a `PREFIX-N` document handle inside a+-- nested record, and adding an unused member to a published record is a+-- compatibility event bought for nothing. It is a cheap additive change for+-- whoever has a motivating case. let Cardinality = ./Cardinality.dhall  let FieldFormat = ./FieldFormat.dhall  let FieldCondition = ./FieldCondition.dhall +let PathReferenceRule = ./PathReferenceRule.dhall+ in  { field : Text     , description : Optional Text     , allowedValues : List Text     , cardinality : Cardinality     , format : Optional FieldFormat+    , path : Optional PathReferenceRule     , when : Optional FieldCondition     }

@@ -0,0 +1,20 @@+--| Policy for a field whose value names a path or URI per OKF v0.2+-- specification §6.2: an absolute URL, a bundle-relative path beginning with+-- `/`, or an ordinary relative path. A relative path resolves against the+-- directory of the concept carrying it, exactly as a Markdown link in that+-- concept's body would.+--+-- Deliberately distinct from `HandleReferenceRule`, which resolves a `PREFIX-N`+-- document handle against the bundle's document-ID index. A path resolves+-- against the bundle's concept tree instead, and declaring both policies on one+-- key is a profile definition error: a value cannot be read as both.+--+-- `externalUriSchemes` lists the URL schemes the profile permits; an empty list+-- means no absolute URL is permitted and the value must be a path. okf resolves+-- only paths, and only to concepts: a path naming a `.md` file must name one+-- that exists in the bundle, and a path naming any other file is accepted+-- without a check, because profile validation never touches the filesystem.+-- `allowSelf` permits a path that resolves to the concept carrying it.+{ externalUriSchemes : List Text+, allowSelf : Bool+}

@@ -16,6 +16,13 @@ -- read or adopt it. Like every description in this schema it is documentary only. -- `allowUnknownFields = False` closes top-level frontmatter to core OKF keys, -- the configured `idField`, and the effective profile/type field rules.+--+-- `requireBundleVersion = Some "0.2"` means the bundle's root `index.md` must+-- declare `okf_version` at that version or later; `None Text` demands nothing and+-- is the default. This is a house convention, not a rule of the format:+-- specification §12 makes the declaration a MAY, so okf itself never asks for one.+-- It is distinct from `okfVersion` above, which says which version's rules this+-- profile writes rather than what it demands of a bundle. let TypeRule = ./TypeRule.dhall  let FrontmatterRules = ./FrontmatterRules.dhall@@ -27,5 +34,6 @@     , allowUnknownTypes : Bool     , allowUnknownFields : Bool     , idField : Optional Text+    , requireBundleVersion : Optional Text     , types : List TypeRule     }

@@ -11,6 +11,8 @@  let HandleReferenceRule = ../HandleReferenceRule.dhall +let PathReferenceRule = ../PathReferenceRule.dhall+ in  { Type = FieldRuleType     , default =       { description = None Text@@ -18,7 +20,9 @@       , cardinality = Cardinality.Any       , format = None FieldFormat       , elementFields = None NestedRules+      , objectFields = None NestedRules       , reference = None HandleReferenceRule+      , path = None PathReferenceRule       , when = None FieldCondition       }     }

@@ -7,12 +7,15 @@  let FieldCondition = ../FieldCondition.dhall +let PathReferenceRule = ../PathReferenceRule.dhall+ in  { Type = NestedFieldRuleType     , default =       { description = None Text       , allowedValues = [] : List Text       , cardinality = Cardinality.Any       , format = None FieldFormat+      , path = None PathReferenceRule       , when = None FieldCondition       }     }

@@ -0,0 +1,13 @@+--| Record-completion defaults for a path-valued field policy.+--+-- The defaults are the strictest coherent policy: no absolute URL is permitted,+-- so the value must be a path, and a path resolving to the concept carrying it+-- is reported. An author widens from there.+let PathReferenceRule = ../PathReferenceRule.dhall++in  { Type = PathReferenceRule+    , default =+      { externalUriSchemes = [] : List Text+      , allowSelf = False+      }+    }

@@ -13,6 +13,7 @@       , allowUnknownTypes = True       , allowUnknownFields = True       , idField = None Text+      , requireBundleVersion = None Text       , types = [] : List TypeRule       }     }

@@ -24,6 +24,8 @@  let HandleReferenceRule = ../defaults/HandleReferenceRule.dhall +let PathReferenceRule = ../defaults/PathReferenceRule.dhall+ in  { plain = \(field : Text) -> FieldRule::{ field }     , documented =         \(field : Text) ->@@ -51,6 +53,16 @@         \(field : Text) ->         \(prefix : Text) ->           FieldRule::{ field, format = Some (FieldFormat.DocumentHandle prefix) }+    , actor = \(field : Text) -> FieldRule::{ field, format = Some FieldFormat.Actor }+    , humanActor =+        \(field : Text) -> FieldRule::{ field, format = Some FieldFormat.HumanActor }+    , integer =+        \(field : Text) -> FieldRule::{ field, format = Some FieldFormat.Integer }+    , nonNegativeInteger =+        \(field : Text) ->+          FieldRule::{ field, format = Some FieldFormat.NonNegativeInteger }+    , boolean =+        \(field : Text) -> FieldRule::{ field, format = Some FieldFormat.Boolean }     , recordList =         \(field : Text) ->         \(elementFields : NestedRules) ->@@ -59,6 +71,18 @@           , cardinality = Cardinality.List           , elementFields = Some elementFields           }+    , record =+        \(field : Text) ->+        \(objectFields : NestedRules) ->+          FieldRule::{ field, objectFields = Some objectFields }+    , recordOrList =+        \(field : Text) ->+        \(fields : NestedRules) ->+          FieldRule::{+          , field+          , objectFields = Some fields+          , elementFields = Some fields+          }     , conditional =         \(rule : FieldRule.Type) ->         \(condition : FieldCondition) ->@@ -78,5 +102,13 @@           , field           , reference =               Some HandleReferenceRule::{ localPrefix, externalUriSchemes }+          }+    , bundlePath = \(field : Text) -> FieldRule::{ field, path = Some PathReferenceRule::{=} }+    , localOrExternalPath =+        \(field : Text) ->+        \(externalUriSchemes : List Text) ->+          FieldRule::{+          , field+          , path = Some PathReferenceRule::{ externalUriSchemes }           }     }

@@ -7,6 +7,8 @@  let FieldCondition = ../FieldCondition.dhall +let PathReferenceRule = ../defaults/PathReferenceRule.dhall+ in  { plain = \(field : Text) -> NestedFieldRule::{ field }     , documented =         \(field : Text) ->@@ -34,8 +36,31 @@         \(field : Text) ->         \(prefix : Text) ->           NestedFieldRule::{ field, format = Some (FieldFormat.DocumentHandle prefix) }+    , actor =+        \(field : Text) -> NestedFieldRule::{ field, format = Some FieldFormat.Actor }+    , humanActor =+        \(field : Text) ->+          NestedFieldRule::{ field, format = Some FieldFormat.HumanActor }+    , integer =+        \(field : Text) -> NestedFieldRule::{ field, format = Some FieldFormat.Integer }+    , nonNegativeInteger =+        \(field : Text) ->+          NestedFieldRule::{ field, format = Some FieldFormat.NonNegativeInteger }+    , boolean =+        \(field : Text) ->+          NestedFieldRule::{ field, format = Some FieldFormat.Boolean }     , conditional =         \(rule : NestedFieldRule.Type) ->         \(condition : FieldCondition) ->           rule with when = Some condition+    , bundlePath =+        \(field : Text) ->+          NestedFieldRule::{ field, path = Some PathReferenceRule::{=} }+    , localOrExternalPath =+        \(field : Text) ->+        \(externalUriSchemes : List Text) ->+          NestedFieldRule::{+          , field+          , path = Some PathReferenceRule::{ externalUriSchemes }+          }     }

@@ -19,6 +19,7 @@ , FieldRule = ./FieldRule.dhall , FieldCondition = ./FieldCondition.dhall , HandleReferenceRule = ./HandleReferenceRule.dhall+, PathReferenceRule = ./PathReferenceRule.dhall , NestedRules = ./NestedRules.dhall , NestedFieldRule = ./NestedFieldRule.dhall , Cardinality = ./Cardinality.dhall@@ -29,6 +30,7 @@   , FrontmatterRules = ./defaults/FrontmatterRules.dhall   , FieldRule = ./defaults/FieldRule.dhall   , HandleReferenceRule = ./defaults/HandleReferenceRule.dhall+  , PathReferenceRule = ./defaults/PathReferenceRule.dhall   , NestedRules = ./defaults/NestedRules.dhall   , NestedFieldRule = ./defaults/NestedFieldRule.dhall   }

@@ -1,6 +1,6 @@ cabal-version:      3.4 name:               okf-core-version:            0.4.0.0+version:            0.5.0.0 synopsis:   Read, validate, index, and traverse Open Knowledge Format bundles @@ -22,10 +22,15 @@ -- The canonical profile schema, plus the fixtures okf-core-test reads. The -- fixture descriptors import the schema through ../../../dhall, so both trees -- must ship for `cabal test` to work from the sdist.+-- The .py and .sql files are not a mistake: the dangling-frontmatter-path and+-- attested-computation fixtures need non-Markdown files in the bundle, because+-- resolving a path to one is the whole point of the checks they exercise. extra-source-files:   dhall/**/*.dhall   test/fixtures/**/*.dhall   test/fixtures/**/*.md+  test/fixtures/**/*.py+  test/fixtures/**/*.sql  common common-options   ghc-options:@@ -45,6 +50,7 @@   import:          common-options   hs-source-dirs:  src   exposed-modules:+    Okf.Actor     Okf.Bundle     Okf.ConceptId     Okf.Discovery@@ -52,9 +58,13 @@     Okf.Graph     Okf.Index     Okf.Log+    Okf.Markdown+    Okf.Path     Okf.Prelude     Okf.Profile+    Okf.Profile.Documentation     Okf.Profile.Registry+    Okf.Trust     Okf.Validation    build-depends:@@ -84,6 +94,7 @@   build-depends:     , aeson     , base          >=4.20 && <5+    , containers    >=0.6  && <0.8     , dhall         >=1.41 && <1.43     , directory     , filepath

@@ -0,0 +1,68 @@+-- | The OKF v0.2 actor convention (specification §7).+--+-- Fields that record an identity — @generated.by@, @verified[].by@, and+-- @sources[].author@ — all carry an /actor/: a short string naming who or what+-- acted. The specification defines exactly three shapes, and consumers that+-- classify trust (§5.3) key off the @human:@ prefix, so the prefix test lives+-- here once rather than being re-derived by each reader.+module Okf.Actor+  ( Actor (..),+    parseActor,+    renderActor,+    isHumanActor,+  )+where++import Data.Text qualified as Text+import Okf.Prelude++-- | An actor as defined by OKF v0.2 specification §7.+--+-- 'parseActor' is total: text matching none of the three shapes becomes+-- 'UnclassifiedActor' rather than a parse failure, because §11 forbids+-- rejecting a document for a malformed optional field. Reporting an+-- unclassified actor is a validation decision, not a parsing one.+data Actor+  = -- | @human:\<id\>@ per specification §7, carrying the id.+    HumanActor !Text+  | -- | @process:\<id\>@ per specification §7, carrying the id.+    ProcessActor !Text+  | -- | @\<producer\>/\<version\>@ per specification §7, carrying producer then version.+    ProducerActor !Text !Text+  | -- | Text matching none of the three shapes, preserved verbatim.+    UnclassifiedActor !Text+  deriving stock (Generic, Eq, Ord, Show)++-- | Classify an actor string. Never fails.+--+-- The @human:@ and @process:@ prefixes are matched before the @\/@ split and+-- matching is case-sensitive, because §7 writes them in lower case and §5.3+-- makes the @human:@ test the sole discriminator between trust tiers. A value+-- such as @Human:ahormati@ is therefore 'UnclassifiedActor'.+--+-- @'renderActor' . 'parseActor'@ is the identity on every input.+parseActor :: Text -> Actor+parseActor raw+  | Just actorId <- Text.stripPrefix "human:" raw, not (Text.null actorId) = HumanActor actorId+  | Just actorId <- Text.stripPrefix "process:" raw, not (Text.null actorId) = ProcessActor actorId+  | (producer, versionWithSlash) <- Text.breakOn "/" raw,+    Just version <- Text.stripPrefix "/" versionWithSlash,+    not (Text.null producer),+    not (Text.null version) =+      ProducerActor producer version+  | otherwise = UnclassifiedActor raw++-- | Render an actor back to the text a producer wrote. Inverse of 'parseActor'.+renderActor :: Actor -> Text+renderActor = \case+  HumanActor actorId -> "human:" <> actorId+  ProcessActor actorId -> "process:" <> actorId+  ProducerActor producer version -> producer <> "/" <> version+  UnclassifiedActor raw -> raw++-- | Whether the actor is a person. Specification §5.3 makes this the sole+-- discriminator between the machine-confirmed and human-reviewed trust tiers.+isHumanActor :: Actor -> Bool+isHumanActor = \case+  HumanActor _ -> True+  _ -> False

@@ -1,17 +1,33 @@ -- | Bundle-level discovery for OKF concept documents. module Okf.Bundle   ( BundleError (..),+    BundleInventory,     Concept,     LogFile (..),+    bundleInventoryMember,+    bundleInventoryOfConcepts,+    walkBundleInventory,     conceptFromDocument,+    conceptAttester,+    conceptComputation,+    conceptComputationSources,     conceptDescription,     conceptDocument,+    conceptExecutor,+    conceptGenerated,     conceptIdOf,+    conceptParameters,     conceptResource,+    conceptRuntime,     conceptSourcePath,+    conceptSources,+    conceptStaleAfter,+    conceptStatus,     conceptTags,+    conceptUsageWindow,     conceptTitle,     conceptType,+    conceptVerified,     findConcept,     findConceptsByDocumentId,     isReservedMarkdownFile,@@ -25,6 +41,8 @@ import Control.Exception (IOException, try) import Data.Aeson.KeyMap qualified as KeyMap import Data.List qualified as List+import Data.Set (Set)+import Data.Set qualified as Set import Data.Text qualified as Text import Data.Text.IO qualified as Text.IO import Okf.ConceptId@@ -49,7 +67,19 @@     title :: !(Maybe Text),     description :: !(Maybe Text),     resource :: !(Maybe Text),-    tags :: ![Text]+    tags :: ![Text],+    generated :: !(Maybe Generated),+    verified :: ![Verification],+    status :: !Status,+    staleAfter :: !(Maybe Text),+    sources :: ![Source],+    usageWindow :: !(Maybe UsageWindow),+    runtime :: !(Maybe Text),+    parameters :: ![Parameter],+    computation :: !(Maybe Text),+    executor :: !(Maybe Executor),+    attester :: !(Maybe Attester),+    computationSources :: ![ComputationSource]   }   deriving stock (Generic, Eq, Show) @@ -60,6 +90,18 @@   | BundleIoError FilePath Text   deriving stock (Generic, Eq, Show) +-- | Every regular file in a bundle, as bundle-relative paths, whether or not okf+-- can parse it. Concepts are the @.md@ subset; a @references\/@ script, a CSV, or+-- an image is here and nowhere else.+--+-- This exists so that a path-valued frontmatter field can be resolved without+-- giving validation a filesystem handle. Validation is offline by design+-- (@docs\/adr\/5-compile-profile-rules-before-validation.md@): it receives parsed+-- values and decides. Reading the inventory once during the walk, where okf is+-- already doing IO, keeps it that way.+newtype BundleInventory = BundleInventory (Set FilePath)+  deriving stock (Generic, Eq, Show)+ -- | A parsed @log.md@ reserved file discovered in a bundle. data LogFile = LogFile   { logSourcePath :: !FilePath,@@ -87,6 +129,38 @@       results <- mapM (readLog root) paths       pure (List.sortOn logSourcePath <$> sequenceA results) +-- | Record every regular file in a bundle, including the ones okf cannot parse.+--+-- A second, independent traversal rather than a widening of 'walkBundle', whose+-- @[Concept]@ result every caller in both packages depends on. Walking twice is+-- mildly wasteful and is the right trade for a change that cannot alter what+-- 'walkBundle' returns.+--+-- Reserved files (@index.md@, @log.md@) are recorded here even though they are+-- not concepts: they are files, and a path-valued field naming one names+-- something that exists.+walkBundleInventory :: FilePath -> IO (Either BundleError BundleInventory)+walkBundleInventory root = do+  discovered <- discoverAllFiles root ""+  pure (BundleInventory . Set.fromList <$> discovered)++-- | Whether the bundle contains a file at the given bundle-relative path. The+-- path is normalised the same way the inventory's entries are, so a caller may+-- pass 'Okf.Path.collapseBundlePath' output directly.+bundleInventoryMember :: FilePath -> BundleInventory -> Bool+bundleInventoryMember path (BundleInventory paths) =+  Set.member (FilePath.normalise path) paths++-- | The inventory an in-memory bundle can honestly report: the concepts' own+-- source paths and nothing else.+--+-- For producers that assemble concepts without a directory to walk. Such a+-- bundle resolves concept-to-concept paths correctly and simply cannot know+-- about a non-Markdown file, because there is no filesystem holding one.+bundleInventoryOfConcepts :: [Concept] -> BundleInventory+bundleInventoryOfConcepts concepts =+  BundleInventory (Set.fromList (FilePath.normalise . conceptSourcePath <$> concepts))+ -- | Find a concept by identifier in an already walked bundle. findConcept :: ConceptId -> [Concept] -> Maybe Concept findConcept conceptId =@@ -137,6 +211,91 @@ conceptTags :: Concept -> [Text] conceptTags Concept {tags} = tags +-- | The OKF v0.2 @generated@ family projected from frontmatter, or 'Nothing'+-- when the concept carries none (or carries one without the @by@ actor that+-- specification §5.2 requires within it).+conceptGenerated :: Concept -> Maybe Generated+conceptGenerated Concept {generated} = generated++-- | The OKF v0.2 @verified@ family projected from frontmatter, empty when the+-- concept carries none. A bare @{ by, at }@ mapping projects as one element,+-- per the specification §5.2 MUST.+--+-- Note what is /not/ here: the trust tier §5.3 derives from this list is a+-- function of it, not a field beside it. See+-- @docs\/adr\/8-derived-not-stored-trust-and-credibility.md@ and use+-- @Okf.Trust.trustTier . conceptVerified@.+conceptVerified :: Concept -> [Verification]+conceptVerified Concept {verified} = verified++-- | The OKF v0.2 @status@ lifecycle field, 'Stable' when the concept carries+-- none (specification §5.4).+conceptStatus :: Concept -> Status+conceptStatus Concept {status} = status++-- | The OKF v0.2 @stale_after@ date read verbatim (specification §5.5).+-- Interpreting it against a calendar day is 'Okf.Trust.staleness''s job.+conceptStaleAfter :: Concept -> Maybe Text+conceptStaleAfter Concept {staleAfter} = staleAfter++-- | The OKF v0.2 @sources@ provenance entries projected from frontmatter,+-- empty when the concept carries none (specification §5.1). Entries lacking the+-- required @resource@ are absent here; 'Okf.Validation.validateDocument'+-- reports them.+conceptSources :: Concept -> [Source]+conceptSources Concept {sources} = sources++-- | The document-scope @usage_window@ that frames every entry's @usage_count@+-- (specification §5.1). Resolve a given entry's effective window with+-- @Okf.Document.effectiveUsageWindow (conceptUsageWindow concept)@, which+-- honours a per-entry override.+conceptUsageWindow :: Concept -> Maybe UsageWindow+conceptUsageWindow Concept {usageWindow} = usageWindow++-- | The @runtime@ that says how an attested computation is run, and so what its+-- @parameters@ mean (specification §10.2).+--+-- Present on any concept that declares it, not only on one whose @type@ is+-- @Attested Computation@: a projection restates what frontmatter says and+-- nothing more. Only 'Okf.Validation.validateDocument' knows that the field is+-- REQUIRED for that one type.+conceptRuntime :: Concept -> Maybe Text+conceptRuntime Concept {runtime} = runtime++-- | The typed, named holes an agent may fill (specification §10.2), empty when+-- the concept declares none. An entry with no @name@ is absent here.+conceptParameters :: Concept -> [Parameter]+conceptParameters Concept {parameters} = parameters++-- | The §6.2 path to a file holding the computation, when the concept names one+-- instead of carrying an inline body fence (specification §10.2, §10.3).+--+-- Verbatim, and not resolved against the bundle. Resolving a path-valued+-- frontmatter field is 'Okf.Validation.validateBundle''s job, which has the+-- 'BundleInventory' this projection does not.+conceptComputation :: Concept -> Maybe Text+conceptComputation Concept {computation} = computation++-- | How the computation is run and what evidence a run must return+-- (specification §10.2). okf never runs it; §10.5 places the run and its receipt+-- outside the bundle.+conceptExecutor :: Concept -> Maybe Executor+conceptExecutor Concept {executor} = executor++-- | The deterministic, no-LLM check that inspects a receipt (specification+-- §10.2). okf never runs it and never computes a verdict.+conceptAttester :: Concept -> Maybe Attester+conceptAttester Concept {attester} = attester++-- | Every computation the concept offers (specification §10.3), file before+-- inline. Empty when it offers none.+--+-- Unlike 'conceptComputation', which restates the frontmatter key verbatim, this+-- also sees the body. §10.3's rule that exactly one of the two forms must be+-- present is 'Okf.Validation.validateDocument''s to report.+conceptComputationSources :: Concept -> [ComputationSource]+conceptComputationSources Concept {computationSources} = computationSources+ -- | Reserved Markdown filenames are not normal concept documents. isReservedMarkdownFile :: FilePath -> Bool isReservedMarkdownFile path =@@ -171,6 +330,31 @@           )       pure (concat <$> sequenceA discovered) +-- | Every regular file under the root, bundle-relative and normalised. Skips+-- directories, recursing into them rather than recording them, because a+-- path-valued field names a file.+discoverAllFiles :: FilePath -> FilePath -> IO (Either BundleError [FilePath])+discoverAllFiles root relativeDir = do+  let absoluteDir = root </> relativeDir+      displayDir = if null relativeDir then root else relativeDir+  listed <- tryBundleIo displayDir (listDirectory absoluteDir)+  case listed of+    Left bundleError -> pure (Left bundleError)+    Right entries -> do+      discovered <-+        for+          (List.sort entries)+          ( \entry -> do+              let relativePath = relativeDir </> entry+                  absolutePath = root </> relativePath+              isDirectory <- tryBundleIo relativePath (doesDirectoryExist absolutePath)+              case isDirectory of+                Left bundleError -> pure (Left bundleError)+                Right True -> discoverAllFiles root relativePath+                Right False -> pure (Right [FilePath.normalise relativePath])+          )+      pure (concat <$> sequenceA discovered)+ discoverLogFiles :: FilePath -> FilePath -> IO (Either BundleError [FilePath]) discoverLogFiles root relativeDir = do   let absoluteDir = root </> relativeDir@@ -249,8 +433,20 @@     )  -- | Build a 'Concept' from its identity and document. The typed projection--- fields (@type_@, @title@, @description@, @resource@, @tags@) are derived from--- the document's frontmatter, so they can never disagree with it. The source+-- fields (@type_@, @title@, @description@, @resource@, @tags@, @generated@,+-- @verified@, @status@, @staleAfter@, @sources@, @usageWindow@, @runtime@,+-- @parameters@, @computation@, @executor@, @attester@) are derived+-- from the document's frontmatter, so they can never disagree with it.+-- A projection may only restate what frontmatter says; it may never store a+-- derivation frontmatter does not carry.+--+-- @computationSources@ is the one field derived from the whole document rather+-- than from frontmatter alone, because specification §10.3 makes the+-- @computation@ key and the body's @# Computation@ section alternatives to each+-- other. Restating what the /document/ says, both halves together, is still+-- restating rather than deriving.+--+-- The source -- path is derived from the concept ID. Use this when assembling concepts in -- memory (for 'writeBundle' or 'Okf.Validation.validateBundle'). conceptFromDocument :: ConceptId -> OKFDocument -> Concept@@ -268,7 +464,19 @@       title = optionalTextField "title" (frontmatter document),       description = optionalTextField "description" (frontmatter document),       resource = optionalTextField "resource" (frontmatter document),-      tags = tagsField (frontmatter document)+      tags = tagsField (frontmatter document),+      generated = readGenerated (frontmatter document),+      verified = readVerified (frontmatter document),+      status = readStatus (frontmatter document),+      staleAfter = readStaleAfter (frontmatter document),+      sources = readSources (frontmatter document),+      usageWindow = readUsageWindow (frontmatter document),+      runtime = readRuntime (frontmatter document),+      parameters = readParameters (frontmatter document),+      computation = readComputation (frontmatter document),+      executor = readExecutor (frontmatter document),+      attester = readAttester (frontmatter document),+      computationSources = readComputationSources document     }  textField :: Text -> Frontmatter -> Text

@@ -7,9 +7,43 @@     frontmatterLookup,     frontmatterKeys,     coreFrontmatterFields,+    fieldsIntroducedInV02,+    fieldsSupersededInV02,     parseDocument,     serializeDocument, +    -- * OKF v0.2 trust family+    Generated (..),+    readGenerated,+    Verification (..),+    readVerified,++    -- * OKF v0.2 lifecycle family+    Status (..),+    readStatus,+    renderStatus,+    readStaleAfter,++    -- * OKF v0.2 provenance family+    Source (..),+    UsageWindow (..),+    readSources,+    readUsageWindow,+    effectiveUsageWindow,++    -- * OKF v0.2 attested computation family+    Parameter (..),+    Executor (..),+    Attester (..),+    attestedComputationType,+    readRuntime,+    readParameters,+    readComputation,+    readExecutor,+    readAttester,+    ComputationSource (..),+    readComputationSources,+     -- * Frontmatter authoring     frontmatterFromFields,     setField,@@ -20,15 +54,23 @@     setTitle,     setDescription,     setTimestamp,+    setGenerated,+    setVerified,+    setStatus,+    setStaleAfter,+    setSources,+    setUsageWindow,     setResource,     setTags,   ) where +import Data.Aeson qualified as Aeson import Data.Aeson.Key qualified as AesonKey import Data.Aeson.KeyMap qualified as KeyMap import Data.Attoparsec.ByteString qualified as Attoparsec import Data.ByteString qualified as ByteString+import Data.Foldable (toList) import Data.Frontmatter qualified as Frontmatter import Data.List qualified as List import Data.Ord (comparing)@@ -39,6 +81,8 @@ import Data.Vector qualified as Vector import Data.Yaml qualified as Yaml import Data.Yaml.Pretty qualified as YamlPretty+import Okf.Actor (Actor, parseActor, renderActor)+import Okf.Markdown (computationBlocks) import Okf.Prelude hiding (setField)  -- | YAML frontmatter fields. OKF allows producer-defined extension keys, so@@ -83,6 +127,470 @@ coreFrontmatterFields :: Set Text coreFrontmatterFields = Set.fromList coreFrontmatterFieldOrder +-- | The OKF v0.2 @generated@ family (specification §5.2): who or what produced+-- the concept's current content, and when.+--+-- @generatedAt@ stays 'Text' rather than a parsed time value for two reasons.+-- §5.2 does not mark @at@ required within the mapping, and okf's convention is+-- to keep frontmatter values exactly as the producer wrote them so+-- serialization round-trips. Checking the value against ISO 8601 belongs to the+-- profile layer, which already has an @Rfc3339Utc@ format for it.+data Generated = Generated+  { generatedBy :: !Actor,+    generatedAt :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++-- | Read the @generated@ family from frontmatter.+--+-- Returns 'Nothing' when the key is absent, when its value is not a YAML+-- mapping, or when the mapping has no textual @by@ — §5.2 makes @by@ REQUIRED+-- within @generated@, so a mapping without one is not a 'Generated'. This never+-- fails: a malformed value is simply not read, because §11 forbids rejecting a+-- document for a malformed optional field. Reporting it is+-- 'Okf.Validation.validateDocument''s job.+readGenerated :: Frontmatter -> Maybe Generated+readGenerated frontmatterValue =+  case frontmatterLookup "generated" frontmatterValue of+    Just (Object generatedFields) -> do+      by <- objectText "by" generatedFields+      pure (Generated (parseActor by) (objectText "at" generatedFields))+    _ -> Nothing++-- | One entry of the OKF v0.2 @verified@ family (specification §5.2): who or+-- what independently confirmed the content, and when.+--+-- Deliberately distinct from 'Generated'. §5.2: "who /wrote/ a concept need not+-- be who /confirmed/ it", and the two are independent — "content can change+-- without re-confirmation, and facts can be re-confirmed without regeneration."+--+-- @verificationAt@ stays 'Text' for the same two reasons as 'generatedAt': §5.2+-- does not mark @at@ required within an entry, and okf preserves frontmatter+-- values as the producer wrote them so serialization round-trips.+data Verification = Verification+  { verificationBy :: !Actor,+    verificationAt :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++-- | Read the OKF v0.2 @verified@ family from frontmatter.+--+-- Handles the two shapes §5.2 permits. A YAML list of mappings yields one+-- 'Verification' per element. A __bare mapping__ yields a one-element list:+-- "Consumers MUST treat a bare mapping as a one-element list", restated in §11's+-- conformance list. Anything else, including an absent key, yields @[]@.+--+-- An entry with no textual @by@ is skipped rather than yielding a partial+-- 'Verification', mirroring 'readGenerated'. An empty result is therefore+-- indistinguishable from an absent key, which is correct: §5.3 keys the+-- unverified tier off the absence of usable verification.+readVerified :: Frontmatter -> [Verification]+readVerified frontmatterValue =+  case frontmatterLookup "verified" frontmatterValue of+    Just (Array entries) -> foldMap (toList . verificationFromValue) entries+    Just bareMapping -> toList (verificationFromValue bareMapping)+    Nothing -> []+  where+    verificationFromValue = \case+      Object entryFields -> do+        by <- objectText "by" entryFields+        pure (Verification (parseActor by) (objectText "at" entryFields))+      _ -> Nothing++-- | The OKF v0.2 @status@ lifecycle field (specification §5.4).+--+-- 'UnknownStatus' carries a value outside the three the specification names,+-- verbatim. §11 forbids rejecting a concept for an unexpected optional value,+-- and preserving the text is what lets 'renderStatus' reproduce exactly what+-- the producer wrote.+data Status+  = -- | @draft@: not yet reviewed; possibly incomplete.+    Draft+  | -- | @stable@: ready for consumption. Also the value an absent key means.+    Stable+  | -- | @deprecated@: kept for links and history; no longer current.+    Deprecated+  | -- | A value outside the three named in §5.4, preserved as written.+    UnknownStatus !Text+  deriving stock (Generic, Eq, Ord, Show)++-- | Read the OKF v0.2 @status@ field (specification §5.4).+--+-- An absent key, or a value that is not text, yields 'Stable': §5.4 states+-- "Absent @status@ ⇒ @stable@". Matching is case-sensitive, consistent with the+-- actor convention of §7 — the specification writes all three values in lower+-- case, and a case-insensitive match would quietly accept a value it should+-- surface as unknown.+readStatus :: Frontmatter -> Status+readStatus frontmatterValue =+  case frontmatterLookup "status" frontmatterValue of+    Just (String "draft") -> Draft+    Just (String "stable") -> Stable+    Just (String "deprecated") -> Deprecated+    Just (String other) -> UnknownStatus other+    _ -> Stable++-- | Render a status back to the text a producer wrote. Inverse of 'readStatus'+-- on every value except an absent key, which reads as 'Stable'.+renderStatus :: Status -> Text+renderStatus = \case+  Draft -> "draft"+  Stable -> "stable"+  Deprecated -> "deprecated"+  UnknownStatus other -> other++-- | Read the OKF v0.2 @stale_after@ field (specification §5.5) verbatim.+--+-- Deliberately unparsed. §5.5 specifies an absolute @YYYY-MM-DD@ date, but+-- parsing here would either lose a malformed value on serialization or force+-- this total reader to fail. Interpreting the date is 'Okf.Trust.staleness''s+-- job, where a comparison is actually needed.+readStaleAfter :: Frontmatter -> Maybe Text+readStaleAfter frontmatterValue =+  case frontmatterLookup "stale_after" frontmatterValue of+    Just (String value) -> Just value+    _ -> Nothing++-- | The date range over which a @usage_count@ was counted (specification §5.1).+--+-- Written once as a sibling of @sources@ to frame every entry's count; a single+-- entry MAY carry its own to override the shared one. Both bounds stay 'Text'+-- and are not parsed into a @Day@, consistent with every other date in the v0.2+-- families: okf preserves the producer's text so serialization round-trips, and+-- format checking belongs to the profile layer's @Date@ format.+data UsageWindow = UsageWindow+  { usageWindowFrom :: !(Maybe Text),+    usageWindowTo :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++-- | One entry of the OKF v0.2 @sources@ family (specification §5.1): a piece of+-- material this concept was derived from, with the optional credibility signals+-- a consumer uses to judge it.+--+-- §5.1 records objective signals rather than a score, because a score "is+-- subjective, unportable across consumers, and goes stale". Nothing here+-- computes a verdict; see+-- @docs\/adr\/8-derived-not-stored-trust-and-credibility.md@.+data Source = Source+  { -- | Optional stable key used to attribute individual claims. §5.1: SHOULD+    -- be present when the body cites the source.+    sourceId :: !(Maybe Text),+    -- | REQUIRED within an entry. Either a concrete artifact a consumer can+    -- follow (absolute URL, bundle-relative path, @references\/@ path) __or a+    -- population or scope descriptor it cannot__, such as+    -- @all queries in BigQuery project X@. Never treat this as a path.+    sourceResource :: !Text,+    -- | Optional human-readable label.+    sourceTitle :: !(Maybe Text),+    -- | Credibility signal: who or what produced the source, in the §7 actor+    -- convention. An authority signal.+    sourceAuthor :: !(Maybe Actor),+    -- | Credibility signal: how often the resource was exercised over the+    -- effective 'UsageWindow'. An adoption and liveness signal. §5.1 warns it+    -- is coarse — comparable at the alive-versus-dead and order-of-magnitude+    -- level, not as a precise ranking — so do not sort or score by it.+    sourceUsageCount :: !(Maybe Integer),+    -- | Credibility signal: when the source itself last changed. A recency+    -- signal, distinct from @generated.at@ (§5.2), which records when the+    -- /concept/ was written.+    sourceLastModified :: !(Maybe Text),+    -- | An entry-local window overriding the document-scope one. Resolve with+    -- 'effectiveUsageWindow' rather than reading this directly.+    sourceUsageWindow :: !(Maybe UsageWindow)+  }+  deriving stock (Generic, Eq, Show)++-- | Read the OKF v0.2 @sources@ family from frontmatter (specification §5.1).+--+-- An entry without a usable @resource@ is skipped, because §5.1 makes it+-- REQUIRED within an entry and a 'Source' without one would be meaningless.+-- Reporting the skipped entry is 'Okf.Validation.validateDocument''s job; this+-- reader stays total so §11's prohibition on rejecting a document is never at+-- risk.+--+-- @usage_count@ is read only from a YAML integer. A numeric string such as+-- @"5000"@ yields 'Nothing': coercing it would make the field's type+-- unpredictable for downstream consumers and would hide a producer mistake.+readSources :: Frontmatter -> [Source]+readSources frontmatterValue =+  case frontmatterLookup "sources" frontmatterValue of+    Just (Array entries) -> foldMap (toList . sourceFromValue) entries+    _ -> []+  where+    sourceFromValue = \case+      Object entryFields -> do+        resource <- objectText "resource" entryFields+        pure+          Source+            { sourceId = objectText "id" entryFields,+              sourceResource = resource,+              sourceTitle = objectText "title" entryFields,+              sourceAuthor = parseActor <$> objectText "author" entryFields,+              sourceUsageCount = objectInteger "usage_count" entryFields,+              sourceLastModified = objectText "last_modified" entryFields,+              sourceUsageWindow = usageWindowFromValue =<< KeyMap.lookup (AesonKey.fromText "usage_window") entryFields+            }+      _ -> Nothing++-- | Read the document-scope @usage_window@, a sibling of @sources@ rather than+-- a member of it (specification §5.1).+readUsageWindow :: Frontmatter -> Maybe UsageWindow+readUsageWindow frontmatterValue =+  usageWindowFromValue =<< frontmatterLookup "usage_window" frontmatterValue++-- | Resolve which window frames a source's @usage_count@, per §5.1: the entry's+-- own window wins when present, otherwise the document-scope one applies.+--+-- This is a named function rather than an inlined fallback because it is the+-- one piece of provenance logic a consumer is most likely to get wrong, and+-- every reader of a @usage_count@ must agree on it.+effectiveUsageWindow :: Maybe UsageWindow -> Source -> Maybe UsageWindow+effectiveUsageWindow documentWindow Source {sourceUsageWindow} =+  sourceUsageWindow <|> documentWindow++usageWindowFromValue :: Value -> Maybe UsageWindow+usageWindowFromValue = \case+  Object windowFields ->+    Just (UsageWindow (objectText "from" windowFields) (objectText "to" windowFields))+  _ -> Nothing++-- | The one @type@ value that carries the OKF v0.2 computation contract+-- (specification §10.1).+--+-- Matched as an exact, case-sensitive string. §4.1 says type values are "not+-- registered centrally" and consumers "MUST tolerate unknown types gracefully",+-- so okf keeps no taxonomy of types; but §10.1 names this one explicitly and+-- §10.5 calls @type: Attested Computation@ "a frontmatter signal", so matching+-- that single literal follows the specification rather than inventing a+-- registry. A document saying @attested computation@ gets no contract handling,+-- which is the tolerance §4.1 asks for.+attestedComputationType :: Text+attestedComputationType = "Attested Computation"++-- | One typed, named hole an agent may fill when running an attested+-- computation (specification §10.2).+--+-- Binding semantics follow the concept's @runtime@: the same entry is a SQL+-- bind variable under @bigquery@, a var under @dbt@, and a function argument+-- under @python@. That is why @runtime@ is the field §10.2 marks REQUIRED —+-- without it a parameter has no meaning.+--+-- @parameterType@ and @parameterRequired@ are optional even though §10.2 writes+-- every entry as @{ name, type, required }@: that describes the shape rather+-- than marking the members REQUIRED, and §11 forbids rejecting a document for a+-- malformed optional field. @parameterName@ is not optional, because an entry+-- naming no hole is not a parameter at all.+data Parameter = Parameter+  { parameterName :: !Text,+    parameterType :: !(Maybe Text),+    parameterRequired :: !(Maybe Bool)+  }+  deriving stock (Generic, Eq, Show)++-- | How an attested computation is run (specification §10.2).+--+-- @executorResource@ names run instructions or code that a runner — an agent,+-- or deterministic consumer code — follows. @executorReceipt@ declares the+-- fields a run must return: the evidence the attester inspects, such as a+-- BigQuery @job_id@ and the SQL the job actually executed.+--+-- okf never runs an executor and never sees a receipt. §10.5 marks the+-- execute-and-attest workflow informative and places its runtime artifacts+-- outside the bundle entirely; this record only says where the instructions+-- live.+data Executor = Executor+  { executorResource :: !(Maybe Text),+    executorReceipt :: ![Text]+  }+  deriving stock (Generic, Eq, Show)++-- | The deterministic check on a run's receipt (specification §10.2).+--+-- @attesterResource@ names code — explicitly with no language model in it —+-- that takes a receipt and returns a verdict, meant to run consumer-side. okf+-- never runs it and never computes a verdict; see+-- @docs\/adr\/8-derived-not-stored-trust-and-credibility.md@ on what okf+-- declines to derive.+--+-- A newtype over one field rather than a bare 'Maybe' 'Text', because §12 lists+-- "the attester ABI, portability, and sandboxing" among the items deferred to a+-- future OKF revision. The record will grow; a named type means it grows+-- without changing every call site.+newtype Attester = Attester {attesterResource :: Maybe Text}+  deriving stock (Generic, Eq, Show)++-- | Read the @runtime@ field (specification §10.2): the system that would+-- execute the computation, such as @bigquery@, @postgres@, @dbt@, @python@, or+-- @Looker@.+--+-- Kept verbatim and never matched against a list of known runtimes. §10.2 gives+-- those five as examples rather than as an enumeration, and a closed set here+-- would reject a correct document naming a runtime okf has not heard of.+--+-- Like every v0.2 reader this never fails: a non-textual value is simply not+-- read. Reporting a missing @runtime@ on an 'attestedComputationType' concept is+-- 'Okf.Validation.validateDocument''s job.+readRuntime :: Frontmatter -> Maybe Text+readRuntime frontmatterValue =+  case frontmatterLookup "runtime" frontmatterValue of+    Just (String value) -> Just value+    _ -> Nothing++-- | Read the @parameters@ list (specification §10.2).+--+-- An entry with no textual @name@ is skipped, exactly as 'readSources' skips an+-- entry with no @resource@: a hole with no name cannot be filled. An absent key,+-- or a value that is not a list, yields @[]@.+--+-- @required@ is read only from a YAML boolean. The string @"true"@ yields+-- 'Nothing', for the same reason 'objectInteger' refuses a numeric string:+-- coercing it would make the field's type unpredictable and hide a producer+-- mistake.+readParameters :: Frontmatter -> [Parameter]+readParameters frontmatterValue =+  case frontmatterLookup "parameters" frontmatterValue of+    Just (Array entries) -> foldMap (toList . parameterFromValue) entries+    _ -> []+  where+    parameterFromValue = \case+      Object entryFields -> do+        name <- objectText "name" entryFields+        pure+          Parameter+            { parameterName = name,+              parameterType = objectText "type" entryFields,+              parameterRequired = objectBool "required" entryFields+            }+      _ -> Nothing++-- | Read the @computation@ field (specification §10.2): a §6.2 path to a file+-- holding the computation, used instead of an inline body fence.+--+-- Deliberately returns the raw text and does __not__ resolve the path. Resolving+-- a path-valued frontmatter field against the bundle is+-- 'Okf.Validation.validateBundle''s job, which has the bundle inventory this+-- reader does not; keeping the reader dumb is also what preserves the+-- round-trip property, since a resolved path is not the text the producer wrote.+--+-- §10.3 makes this key and the body's @# Computation@ fence mutually exclusive.+-- Checking that is body inspection and is not done here.+readComputation :: Frontmatter -> Maybe Text+readComputation frontmatterValue =+  case frontmatterLookup "computation" frontmatterValue of+    Just (String value) -> Just value+    _ -> Nothing++-- | Read the @executor@ mapping (specification §10.2).+--+-- Returns 'Nothing' when the key is absent or its value is not a mapping. Unlike+-- 'readGenerated' no member is mandatory, because §10.2 marks none of them+-- REQUIRED: an @executor@ carrying only a @receipt@ still says something a+-- consumer can use.+--+-- A @receipt@ written as a bare string rather than a list is read as a+-- one-element list, mirroring how §5.2's @verified@ tolerates a bare mapping+-- where a list is expected. A non-textual list element is dropped.+readExecutor :: Frontmatter -> Maybe Executor+readExecutor frontmatterValue =+  case frontmatterLookup "executor" frontmatterValue of+    Just (Object executorFields) ->+      Just+        Executor+          { executorResource = objectText "resource" executorFields,+            executorReceipt = objectTextList "receipt" executorFields+          }+    _ -> Nothing++-- | Read the @attester@ mapping (specification §10.2).+--+-- Returns 'Nothing' when the key is absent or its value is not a mapping. An+-- @attester@ mapping with no @resource@ still reads as an 'Attester' carrying+-- 'Nothing': §10.2 marks no member REQUIRED, and the distinction between "no+-- attester declared" and "an attester declared badly" is one a diagnostic can+-- make only if the reader keeps it.+readAttester :: Frontmatter -> Maybe Attester+readAttester frontmatterValue =+  case frontmatterLookup "attester" frontmatterValue of+    Just (Object attesterFields) -> Just (Attester (objectText "resource" attesterFields))+    _ -> Nothing++-- | Where an attested computation's computation actually lives (specification+-- §10.3).+data ComputationSource+  = -- | A code block in the body's @# Computation@ section, carrying its literal+    -- contents.+    ComputationInline !Text+  | -- | The §6.2 path in the @computation@ frontmatter key, verbatim and not+    -- resolved against the bundle.+    ComputationFile !Text+  deriving stock (Generic, Eq, Show)++-- | Every computation the document offers, file before inline.+--+-- §10.3 requires exactly one — "Inline: a single fenced code block in the body+-- under @# Computation@" or "File: set @computation@ to a path (§6.2) and omit+-- the body fence" — and this reader deliberately does not enforce that. Like+-- every reader in this module it restates what the document says and never+-- fails. A list with none, or with two, is what+-- 'Okf.Validation.validateDocument' reports.+--+-- This is the first reader here that takes an 'OKFDocument' rather than a+-- 'Frontmatter', because §10.3 is the first rule in OKF that spans both halves+-- of a document: the frontmatter key and the body section are alternatives to+-- each other, so neither half can answer the question alone.+--+-- Type-agnostic, matching every other projection here: a @# Computation@+-- section on a @Metric@ is still a fact about that document. Scoping a report to+-- 'attestedComputationType' is "Okf.Validation"'s job.+readComputationSources :: OKFDocument -> [ComputationSource]+readComputationSources OKFDocument {frontmatter = documentFrontmatter, body = documentBody} =+  foldMap (pure . ComputationFile) (readComputation documentFrontmatter)+    <> map ComputationInline (computationBlocks documentBody)++-- | Read an integral member. Only a YAML integer qualifies: a numeric string+-- and a fractional number both yield 'Nothing', because aeson's @Integer@+-- decoder rejects each. Coercing either would make the field's type+-- unpredictable for downstream consumers and would hide a producer mistake.+objectInteger :: Text -> KeyMap.KeyMap Value -> Maybe Integer+objectInteger key members =+  case KeyMap.lookup (AesonKey.fromText key) members of+    Just value@(Number _) ->+      case Aeson.fromJSON value of+        Aeson.Success parsed -> Just parsed+        Aeson.Error _ -> Nothing+    _ -> Nothing++objectText :: Text -> KeyMap.KeyMap Value -> Maybe Text+objectText key members =+  case KeyMap.lookup (AesonKey.fromText key) members of+    Just (String value) -> Just value+    _ -> Nothing++-- | Read a boolean member. Only a YAML boolean qualifies; the string @"true"@+-- yields 'Nothing', for the same reason 'objectInteger' refuses a numeric+-- string.+objectBool :: Text -> KeyMap.KeyMap Value -> Maybe Bool+objectBool key members =+  case KeyMap.lookup (AesonKey.fromText key) members of+    Just (Bool value) -> Just value+    _ -> Nothing++-- | Read a member that is a list of strings, tolerating a bare string as a+-- one-element list. Non-textual elements are dropped rather than failing, and an+-- absent or otherwise-shaped value yields @[]@ — the same shape 'tagsField' in+-- @Okf.Bundle@ gives @tags@.+objectTextList :: Text -> KeyMap.KeyMap Value -> [Text]+objectTextList key members =+  case KeyMap.lookup (AesonKey.fromText key) members of+    Just (Array values) -> foldMap textValue (toList values)+    Just (String value) -> [value]+    _ -> []+  where+    textValue = \case+      String value -> [value]+      _ -> []+ -- | Build frontmatter from a list of @(key, value)@ pairs. Later duplicate -- keys overwrite earlier ones. frontmatterFromFields :: [(Text, Value)] -> Frontmatter@@ -134,10 +642,96 @@ setDescription :: Text -> Frontmatter -> Frontmatter setDescription value = setField "description" (String value) --- | Set the @timestamp@ field.+-- | Set the OKF v0.1 @timestamp@ field.+--+-- OKF v0.2 supersedes @timestamp@ with @generated.at@ (specification §13.1);+-- 'setGenerated' writes the v0.2 form. This is kept for producers deliberately+-- writing v0.1 bundles, which okf continues to read and write. See+-- @docs\/adr\/7-okf-v0-1-legacy-fallback-policy.md@. setTimestamp :: Text -> Frontmatter -> Frontmatter setTimestamp value = setField "timestamp" (String value) +-- | Set the OKF v0.2 @generated@ field as a YAML mapping with @by@ and, when+-- present, @at@ (specification §5.2). This is the single place that knows+-- @generated@ is a mapping of an actor and a datetime.+setGenerated :: Generated -> Frontmatter -> Frontmatter+setGenerated Generated {generatedBy, generatedAt} =+  setField "generated" (actorMapping generatedBy generatedAt)++-- | Set the OKF v0.2 @verified@ field (specification §5.2).+--+-- Always writes a YAML list, even for one entry. §5.2 permits the bare-mapping+-- form on input and 'readVerified' honours that MUST, but writing it would be+-- pointlessly ambiguous when the list is the specification's primary form.+setVerified :: [Verification] -> Frontmatter -> Frontmatter+setVerified verifications =+  setField "verified" (Array (Vector.fromList (entryValue <$> verifications)))+  where+    entryValue Verification {verificationBy, verificationAt} =+      actorMapping verificationBy verificationAt++-- | Set the OKF v0.2 @status@ field (specification §5.4).+setStatus :: Status -> Frontmatter -> Frontmatter+setStatus status = setField "status" (String (renderStatus status))++-- | Set the OKF v0.2 @stale_after@ field (specification §5.5). The value is an+-- absolute @YYYY-MM-DD@ date; it is written as given and not validated here.+setStaleAfter :: Text -> Frontmatter -> Frontmatter+setStaleAfter value = setField "stale_after" (String value)++-- | Set the OKF v0.2 @sources@ field as a YAML list of mappings (§5.1).+--+-- Every optional key that is 'Nothing' is omitted rather than written as an+-- explicit null, so a round-trip through 'readSources' is lossless and a+-- generated document carries no noise. This is the single place that knows the+-- shape of a source entry.+setSources :: [Source] -> Frontmatter -> Frontmatter+setSources sources =+  setField "sources" (Array (Vector.fromList (sourceValue <$> sources)))+  where+    sourceValue source =+      Object+        ( KeyMap.fromList+            ( concat+                [ [(AesonKey.fromText "id", String value) | Just value <- [sourceId source]],+                  [(AesonKey.fromText "resource", String (sourceResource source))],+                  [(AesonKey.fromText "title", String value) | Just value <- [sourceTitle source]],+                  [(AesonKey.fromText "author", String (renderActor value)) | Just value <- [sourceAuthor source]],+                  [(AesonKey.fromText "usage_count", Number (fromInteger value)) | Just value <- [sourceUsageCount source]],+                  [(AesonKey.fromText "last_modified", String value) | Just value <- [sourceLastModified source]],+                  [(AesonKey.fromText "usage_window", usageWindowValue value) | Just value <- [sourceUsageWindow source]]+                ]+            )+        )++-- | Set the document-scope @usage_window@ that frames every @usage_count@+-- (specification §5.1).+setUsageWindow :: UsageWindow -> Frontmatter -> Frontmatter+setUsageWindow window = setField "usage_window" (usageWindowValue window)++usageWindowValue :: UsageWindow -> Value+usageWindowValue UsageWindow {usageWindowFrom, usageWindowTo} =+  Object+    ( KeyMap.fromList+        ( concat+            [ [(AesonKey.fromText "from", String value) | Just value <- [usageWindowFrom]],+              [(AesonKey.fromText "to", String value) | Just value <- [usageWindowTo]]+            ]+        )+    )++-- | A @{ by, at }@ YAML mapping, omitting @at@ when absent. Shared by the+-- @generated@ and @verified@ families, which specification §5.2 gives the same+-- shape.+actorMapping :: Actor -> Maybe Text -> Value+actorMapping actor occurredAt =+  Object+    ( KeyMap.fromList+        ( (AesonKey.fromText "by", String (renderActor actor))+            : [(AesonKey.fromText "at", String atValue) | Just atValue <- [occurredAt]]+        )+    )+ -- | Set the @resource@ field. setResource :: Text -> Frontmatter -> Frontmatter setResource value = setField "resource" (String value)@@ -157,9 +751,9 @@         else Right (OKFDocument emptyFrontmatter input)  -- | Serialize to a normalized YAML-frontmatter Markdown document. Frontmatter--- keys are emitted in a deterministic order (the six common OKF fields first —--- @type, title, description, timestamp, resource, tags@ — then every other key--- in ascending alphabetical order) so regenerating a bundle yields minimal diffs.+-- keys are emitted in a deterministic order ('coreFrontmatterFieldOrder' first,+-- in that fixed order, then every other key in ascending alphabetical order) so+-- regenerating a bundle yields minimal diffs. serializeDocument :: OKFDocument -> Text serializeDocument OKFDocument {frontmatter, body} =   Text.unlines ["---", renderedYaml, "---", ""] <> ensureTrailingNewline body@@ -175,9 +769,9 @@   where     config = YamlPretty.setConfCompare (comparing okfKeyRank) YamlPretty.defConfig --- | Sort key for deterministic frontmatter ordering: the six common OKF fields--- come first in their fixed order; every other key sorts after them--- alphabetically by its text form.+-- | Sort key for deterministic frontmatter ordering: the core OKF fields come+-- first in their fixed 'coreFrontmatterFieldOrder'; every other key sorts after+-- them alphabetically by its text form. okfKeyRank :: Text -> (Int, Text) okfKeyRank keyText =   case lookup keyText commonRanks of@@ -186,8 +780,103 @@   where     commonRanks = zip coreFrontmatterFieldOrder [0 ..] +-- | The deterministic OKF concept-level key order: identity first, then the+-- v0.2 lifecycle field (§5.4), then the v0.2 attested computation contract+-- (§10.2), then the v0.2 trust families (§5.2, §5.5), then the v0.2 provenance+-- family (§5.1), then the v0.1 @timestamp@ superseded by @generated.at@ (§13.1).+--+-- The five computation keys sit between @status@ and @generated@ because that is+-- where §10.2's own worked example puts them, so a concept copied out of the+-- specification and regenerated by okf comes back in the order its author wrote.+-- They are in this list at all for the reason+-- [ADR 7](docs/adr/7-okf-v0-1-legacy-fallback-policy.md) gives for the six v0.2+-- concept keys before them: the list "exists to name the keys the format itself+-- defines", §13.2 makes these five format-defined, and leaving them out would+-- make a closed profile (@allowUnknownFields = False@) reject a conformant+-- Attested Computation until its author redeclared five keys they did not+-- choose — "a tax that grows with every specification revision". That they are+-- meaningful for exactly one @type@, unlike every other key here, does not+-- change the answer: closure governs /unknown/ keys, and a key §13.2 names is+-- not unknown. A profile that wants to reject @runtime@ on a @Metric@ says so+-- with a @TypeRule@, which is the layer that knows about types.+--+-- @okf_version@ is deliberately absent: it is an index-level key that appears+-- only in a bundle-root @index.md@ (§12), never on a concept. coreFrontmatterFieldOrder :: [Text]-coreFrontmatterFieldOrder = ["type", "title", "description", "timestamp", "resource", "tags"]+coreFrontmatterFieldOrder =+  [ "type",+    "title",+    "description",+    "resource",+    "tags",+    "status",+    "runtime",+    "parameters",+    "computation",+    "executor",+    "attester",+    "generated",+    "verified",+    "stale_after",+    "sources",+    "usage_window",+    "timestamp"+  ]++-- | Concept-level frontmatter keys that OKF v0.2 introduced (specification+-- §13.2), as reference data.+--+-- __Deliberately not used as a compile-time profile check.__ It is tempting to+-- reject a profile that declares @okfVersion = "0.1"@ and names one of these,+-- and that check was written and then removed. A profile key /name/ does not+-- imply the OKF core key of that name: per+-- @docs\/adr\/1-profile-declared-document-ids.md@, constraining keys the core+-- format does not own is what profiles are /for/, and @status@, @sources@, and+-- @verified@ are ordinary words that teams were already using as house+-- conventions before v0.2 claimed them. Rejecting+-- @field.documented "status" "One of: proposed, accepted, superseded."@ for+-- naming an ADR lifecycle would be a false positive on a pinned descriptor okf+-- cannot see. See @docs\/adr\/11-growing-the-profile-descriptor-language.md@ on+-- retroactive definition errors.+--+-- 'fieldsSupersededInV02' is checked, because it is the asymmetric case: it+-- fires only when the profile has declared v0.2 or later, which is an opt-in to+-- v0.2 semantics under which the key unambiguously means the core one.+--+-- Deliberately kept beside 'coreFrontmatterFieldOrder' and deliberately not+-- merged into it. That list answers "which keys does okf own", which is a+-- different question with different consumers — serialization order, and the set+-- of keys a closed profile always permits, per+-- [ADR 7](docs/adr/7-okf-v0-1-legacy-fallback-policy.md). Merging the two would+-- couple a version question to a permission question.+--+-- A plain @[Text]@ rather than a map to 'Okf.Index.OkfVersion' because+-- @Okf.Index@ imports this module; pairing a key with a version happens in+-- @Okf.Profile@, which imports both.+fieldsIntroducedInV02 :: [Text]+fieldsIntroducedInV02 =+  [ "status",+    "generated",+    "verified",+    "stale_after",+    "sources",+    "usage_window",+    -- §13.2's second bullet: "New concept type `Attested Computation` and its+    -- computation keys `runtime`, `parameters`, `computation`, `executor`,+    -- `attester` (§10)."+    "runtime",+    "parameters",+    "computation",+    "executor",+    "attester"+  ]++-- | Concept-level frontmatter keys OKF v0.2 superseded (specification §13.1).+-- @timestamp@ is superseded by @generated.at@. okf still /reads/ it, per+-- [ADR 7](docs/adr/7-okf-v0-1-legacy-fallback-policy.md); a profile that+-- /demands/ it while declaring v0.2 is asking authors to write a retired key.+fieldsSupersededInV02 :: [Text]+fieldsSupersededInV02 = ["timestamp"]  parseFrontmatterDocument :: ByteString.ByteString -> Either DocumentParseError OKFDocument parseFrontmatterDocument inputBytes =

@@ -11,7 +11,6 @@ where  import CMarkGFM qualified-import Control.Monad (foldM) import Data.Aeson (ToJSON (..), object, (.=)) import Data.List qualified as List import Data.Map.Strict qualified as Map@@ -20,8 +19,9 @@ import Okf.Bundle import Okf.ConceptId import Okf.Document (body)+import Okf.Markdown (markdownOptions)+import Okf.Path (PathReference (..), classifyPathReference) import Okf.Prelude hiding ((.=))-import System.FilePath ((</>)) import System.FilePath qualified as FilePath  -- | A graph node for one concept.@@ -135,28 +135,33 @@  extractMarkdownLinks :: Text -> [Text] extractMarkdownLinks markdown =-  walk (CMarkGFM.commonmarkToNode [] [] markdown)+  walk (CMarkGFM.commonmarkToNode markdownOptions [] markdown)   where     walk (CMarkGFM.Node _ nodeType childNodes) =       case nodeType of         CMarkGFM.LINK url _title -> [url]         _ -> foldMap walk childNodes +-- | Resolve one Markdown link destination to the concept it names, if any.+--+-- The §6.2 grammar lives in 'Okf.Path' and is shared with the profile layer, but+-- this function deliberately differs from it in one place, and the difference is+-- the point of keeping 'isExternalUrl' here. A body link is a heuristic over+-- prose, so only the three schemes a Markdown author plausibly writes are+-- treated as external, and anything that resolves to no concept is dropped in+-- silence — OKF v0.2 §6.1 says a broken body link may be knowledge not yet+-- written. A path-valued /field/ is read the other way round: every scheme is+-- recognized, and one the profile did not permit is reported rather than+-- ignored. resolveLink :: Concept -> Text -> [ConceptId] resolveLink concept rawUrl   | isExternalUrl rawUrl = []-  | FilePath.takeExtension cleanPath /= ".md" = []-  | otherwise = maybe [] (either (const []) pure . conceptIdFromFilePath) bundleRelativePath-  where-    cleanPath = Text.unpack (stripUrlSuffix rawUrl)-    sourceDirectory = FilePath.takeDirectory (conceptIdToFilePath (conceptIdOf concept))-    bundleRelativePath-      | "/" `Text.isPrefixOf` rawUrl = collapseBundlePath (dropWhile (== '/') cleanPath)-      | otherwise = collapseBundlePath (sourceDirectory </> cleanPath)--stripUrlSuffix :: Text -> Text-stripUrlSuffix =-  Text.takeWhile (\char -> char /= '#' && char /= '?')+  | otherwise =+      case classifyPathReference (conceptIdOf concept) rawUrl of+        BundlePath resolved+          | FilePath.takeExtension resolved == ".md" ->+              either (const []) pure (conceptIdFromFilePath resolved)+        _ -> []  isExternalUrl :: Text -> Bool isExternalUrl rawUrl =@@ -164,13 +169,3 @@    in "http://" `Text.isPrefixOf` lower         || "https://" `Text.isPrefixOf` lower         || "mailto:" `Text.isPrefixOf` lower--collapseBundlePath :: FilePath -> Maybe FilePath-collapseBundlePath =-  fmap FilePath.joinPath . foldM step [] . FilePath.splitDirectories-  where-    step [] "." = Just []-    step acc "." = Just acc-    step [] ".." = Nothing-    step acc ".." = Just (init acc)-    step acc segment = Just (acc <> [segment])

@@ -1,30 +1,158 @@--- | Deterministic Markdown index rendering for OKF bundle directories.+-- | Deterministic Markdown index rendering for OKF bundle directories, and the+-- bundle-root version declaration of specification §12. module Okf.Index   ( renderBundleIndexes,+    renderBundleIndexesWith,     renderIndex,+    renderRootIndex,     writeBundleIndexes,+    writeBundleIndexesWith,++    -- * OKF version declaration (specification §12)+    OkfVersion (..),+    VersionDeclaration (..),+    readBundleVersion,+    parseOkfVersion,+    renderOkfVersion,+    supportedOkfVersion,   ) where +import Control.Exception (IOException, try)+import Data.Aeson.Text qualified as Aeson.Text+import Data.Char qualified as Char import Data.List qualified as List import Data.Map.Strict qualified as Map import Data.Text qualified as Text import Data.Text.IO qualified as Text.IO+import Data.Text.Lazy qualified as Text.Lazy import Okf.Bundle+import Okf.Document (OKFDocument (..), frontmatterLookup, parseDocument) import Okf.Prelude import System.Directory   ( doesDirectoryExist,+    doesFileExist,     listDirectory,   ) import System.FilePath ((</>)) import System.FilePath qualified as FilePath+import System.IO.Error (ioeGetErrorString)+import Text.Read (readMaybe) --- | Render an @index.md@ for one bundle directory from its immediate concepts--- and subdirectory names.-renderIndex :: [FilePath] -> [Concept] -> Text-renderIndex subdirectories concepts =-  Text.intercalate "\n" (filter (not . Text.null) [subdirectorySection, conceptSections]) <> "\n"+-- | An OKF format version, written @\<major\>.\<minor\>@ (specification §12).+--+-- The derived 'Ord' compares major before minor, which is what §12's+-- "a minor version bump introduces backward-compatible additions" needs: a+-- consumer may read any declaration at or below the highest version it+-- understands within the same major.+data OkfVersion = OkfVersion+  { okfVersionMajor :: !Int,+    okfVersionMinor :: !Int+  }+  deriving stock (Generic, Eq, Ord, Show)++-- | What a bundle's root @index.md@ says about the version it targets.+--+-- All three cases are readable. §12 makes the declaration a MAY, so an absent+-- one is the ordinary case rather than a defect, and a malformed one is worth a+-- strict-authoring diagnostic but never a refusal.+data VersionDeclaration+  = VersionDeclared !OkfVersion+  | VersionUndeclared+  | -- | The key is present but its value is not @\<major\>.\<minor\>@. Carries+    -- the value as the author wrote it, so a diagnostic can quote it back.+    VersionUnparseable !Text+  deriving stock (Generic, Eq, Show)++-- | The highest OKF version this library understands. Specification §12's+-- best-effort rule is applied against this value: see+-- @Okf.Validation.versionGate@, which is the one place that decides what a+-- declared version implies.+supportedOkfVersion :: OkfVersion+supportedOkfVersion = OkfVersion {okfVersionMajor = 0, okfVersionMinor = 2}++-- | Render a version back to its @\<major\>.\<minor\>@ text form.+renderOkfVersion :: OkfVersion -> Text+renderOkfVersion OkfVersion {okfVersionMajor, okfVersionMinor} =+  Text.pack (show okfVersionMajor) <> "." <> Text.pack (show okfVersionMinor)++-- | Parse a @\<major\>.\<minor\>@ version. Exactly two dot-separated runs of+-- ASCII digits; anything else is unparseable.+parseOkfVersion :: Text -> Maybe OkfVersion+parseOkfVersion rawVersion =+  case Text.splitOn "." (Text.strip rawVersion) of+    [majorText, minorText] ->+      OkfVersion <$> digits majorText <*> digits minorText+    _ -> Nothing   where+    digits component+      | Text.null component = Nothing+      | Text.all Char.isDigit component = readMaybe (Text.unpack component)+      | otherwise = Nothing++-- | Read the version a bundle declares in its root @index.md@ frontmatter.+--+-- §8 permits frontmatter in exactly one @index.md@, the bundle root's, and §12+-- permits exactly one key in it. This reads that key and nothing else; it does+-- not turn @index.md@ into a concept, which stays reserved by+-- 'Okf.Bundle.isReservedMarkdownFile'.+--+-- A missing root @index.md@, one with no frontmatter, one whose frontmatter+-- omits the key, and one whose frontmatter does not parse all yield+-- 'VersionUndeclared'. Only a present key with an unreadable value yields+-- 'VersionUnparseable'. The 'Left' is reserved for genuine IO failure.+readBundleVersion :: FilePath -> IO (Either BundleError VersionDeclaration)+readBundleVersion root = do+  let indexPath = root </> "index.md"+  exists <- doesFileExist indexPath+  if not exists+    then pure (Right VersionUndeclared)+    else do+      loaded <- try (Text.IO.readFile indexPath)+      pure $ case loaded of+        Left (exception :: IOException) ->+          Left (BundleIoError "index.md" (Text.pack (ioeGetErrorString exception)))+        Right content ->+          Right $ case parseDocument content of+            Left _ -> VersionUndeclared+            Right OKFDocument {frontmatter} ->+              case frontmatterLookup "okf_version" frontmatter of+                Nothing -> VersionUndeclared+                Just value -> declarationFromValue value++-- | Read the declared value, accepting both the quoted string form the+-- specification writes (@okf_version: "0.2"@) and the bare YAML number a+-- careless author writes (@okf_version: 0.2@). A bundle should not become+-- unreadable over a missing pair of quotes.+declarationFromValue :: Value -> VersionDeclaration+declarationFromValue value =+  case parseOkfVersion rendered of+    Just version -> VersionDeclared version+    Nothing -> VersionUnparseable rendered+  where+    rendered = case value of+      String text -> text+      -- Everything else is quoted back through JSON so the diagnostic can show+      -- what was written. A YAML number reaches here as @0.2@, which parses.+      other -> Text.Lazy.toStrict (Aeson.Text.encodeToLazyText other)++-- | Render an @index.md@ for one bundle directory from its immediate concepts,+-- subdirectory names, and non-concept files.+--+-- Specification §8 says an index "enumerates the directory's contents to support+-- progressive disclosure". A directory holding only+-- @references\/attesters\/revenue.py@ has contents, and before the files+-- parameter existed its generated index was a single newline — which is exactly+-- the directory shape §6.3's @references\/@ convention encourages. See+-- @docs\/adr\/13-the-references-convention-and-non-markdown-files.md@.+--+-- The files given are those that are not concepts and not reserved: in practice+-- every regular file whose extension is not @.md@. Dotfiles are excluded by the+-- caller, so a stray @.DS_Store@ never reaches a committed index.+renderIndex :: [FilePath] -> [FilePath] -> [Concept] -> Text+renderIndex subdirectories files concepts =+  Text.intercalate "\n" (filter (not . Text.null) [subdirectorySection, fileSection, conceptSections]) <> "\n"+  where     sortedSubdirectories = List.sort subdirectories     subdirectorySection       | null sortedSubdirectories = ""@@ -35,6 +163,11 @@                 : (directoryBullet <$> sortedSubdirectories)             ) +    sortedFiles = List.sort files+    fileSection+      | null sortedFiles = ""+      | otherwise = Text.unlines ("# Files" : "" : (fileBullet <$> sortedFiles))+     groupedConcepts = Map.toAscList (foldr addConcept Map.empty concepts)     conceptSections =       Text.intercalate "\n" (sectionForType <$> groupedConcepts)@@ -51,10 +184,41 @@         : (conceptBullet <$> List.sortOn conceptSourcePath concepts)     ) +-- | Render the bundle-root @index.md@, which is the one index permitted to+-- carry frontmatter (specification §8) and the one place a bundle declares the+-- version it targets (§12).+--+-- With no version this is exactly 'renderIndex', so a bundle that declares+-- nothing keeps a frontmatter-free root index. The value is quoted because §12+-- writes it quoted and because an unquoted @0.2@ is a YAML float whose text+-- form no serializer guarantees to preserve.+renderRootIndex :: Maybe OkfVersion -> [FilePath] -> [FilePath] -> [Concept] -> Text+renderRootIndex version = renderRootIndexText (renderOkfVersion <$> version)++-- | 'renderRootIndex' over the declaration's raw text rather than a parsed+-- version, so that a declaration okf cannot parse survives regeneration+-- verbatim instead of being deleted.+renderRootIndexText :: Maybe Text -> [FilePath] -> [FilePath] -> [Concept] -> Text+renderRootIndexText Nothing subdirectories files concepts =+  renderIndex subdirectories files concepts+renderRootIndexText (Just versionText) subdirectories files concepts =+  Text.unlines ["---", "okf_version: \"" <> escaped versionText <> "\"", "---", ""]+    <> renderIndex subdirectories files concepts+  where+    -- The only two characters that can end a double-quoted YAML scalar early.+    -- A parsed version can contain neither; a preserved raw one might.+    escaped = Text.replace "\"" "\\\"" . Text.replace "\\" "\\\\"+ directoryBullet :: FilePath -> Text directoryBullet directory =   "- [" <> Text.pack directory <> "/](" <> Text.pack directory <> "/index.md)" +-- | A file has no frontmatter, so there is no title to prefer and no description+-- to append: the link text is the name.+fileBullet :: FilePath -> Text+fileBullet file =+  "- [" <> Text.pack file <> "](" <> Text.pack file <> ")"+ conceptBullet :: Concept -> Text conceptBullet concept =   "- ["@@ -64,26 +228,56 @@     <> ")"     <> maybe "" (" - " <>) (conceptDescription concept) --- | Write deterministic @index.md@ files for every directory in a bundle.+-- | Write deterministic @index.md@ files for every directory in a bundle,+-- preserving any version declaration the root index already carries. writeBundleIndexes :: FilePath -> IO (Either BundleError ())-writeBundleIndexes root = do-  rendered <- renderBundleIndexes root+writeBundleIndexes = writeBundleIndexesWith Nothing++-- | 'writeBundleIndexes' with an explicit version declaration for the bundle+-- root. 'Just' overrides whatever the root index carries; 'Nothing' preserves+-- it.+writeBundleIndexesWith :: Maybe OkfVersion -> FilePath -> IO (Either BundleError ())+writeBundleIndexesWith override root = do+  rendered <- renderBundleIndexesWith override root   case rendered of     Left bundleError -> pure (Left bundleError)     Right indexes -> do       mapM_ (\(relativePath, content) -> Text.IO.writeFile (root </> relativePath) content) indexes       pure (Right ()) --- | Render every @index.md@ file that would be written for a bundle.+-- | Render every @index.md@ file that would be written for a bundle,+-- preserving any version declaration the root index already carries. renderBundleIndexes :: FilePath -> IO (Either BundleError [(FilePath, Text)])-renderBundleIndexes root = do+renderBundleIndexes = renderBundleIndexesWith Nothing++-- | 'renderBundleIndexes' with an explicit version declaration for the bundle+-- root. 'Just' overrides whatever the root index carries; 'Nothing' preserves+-- it.+--+-- Preserving is not a nicety. Index generation rewrites every directory's+-- @index.md@, root included, so without reading the existing declaration first+-- a single @okf index --write@ would silently delete the bundle's §12 version+-- declaration.+renderBundleIndexesWith :: Maybe OkfVersion -> FilePath -> IO (Either BundleError [(FilePath, Text)])+renderBundleIndexesWith override root = do   walked <- walkBundle root-  case walked of+  declared <- readBundleVersion root+  case (,) <$> walked <*> declared of     Left bundleError -> pure (Left bundleError)-    Right concepts -> do+    Right (concepts, declaration) -> do+      let rootVersion = (renderOkfVersion <$> override) <|> declaredText declaration       directories <- indexDirectories root concepts-      indexes <- mapM (renderDirectoryIndex root concepts) directories+      indexes <- mapM (renderDirectoryIndex rootVersion root concepts) directories       pure (Right indexes)+  where+    declaredText = \case+      VersionDeclared version -> Just (renderOkfVersion version)+      -- An unparseable declaration is preserved as written and left for+      -- validation to report. Rewriting it to a version okf invented would+      -- destroy the author's text; dropping it would be exactly the data loss+      -- this function exists to prevent.+      VersionUnparseable rawVersion -> Just rawVersion+      VersionUndeclared -> Nothing  indexDirectories :: FilePath -> [Concept] -> IO [FilePath] indexDirectories root concepts = do@@ -106,15 +300,21 @@       )       entries -renderDirectoryIndex :: FilePath -> [Concept] -> FilePath -> IO (FilePath, Text)-renderDirectoryIndex root concepts relativeDir = do+-- | Render one directory's index. The bundle root reaches this twice, once as+-- @\"\"@ and once as @\".\"@, and both normalise to the same @index.md@; only+-- the root carries the version declaration.+renderDirectoryIndex :: Maybe Text -> FilePath -> [Concept] -> FilePath -> IO (FilePath, Text)+renderDirectoryIndex rootVersion root concepts relativeDir = do   subdirectories <- immediateSubdirectories root relativeDir+  files <- immediateFiles root relativeDir   let immediateConcepts =         List.filter           (\concept -> FilePath.normalise (FilePath.takeDirectory (conceptSourcePath concept)) == FilePath.normalise relativeDir)           concepts       indexPath = relativeDir </> "index.md"-  pure (FilePath.normalise indexPath, renderIndex subdirectories immediateConcepts)+      isBundleRoot = FilePath.normalise indexPath == "index.md"+      renderFor = if isBundleRoot then renderRootIndexText rootVersion else renderIndex+  pure (FilePath.normalise indexPath, renderFor subdirectories files immediateConcepts)  immediateSubdirectories :: FilePath -> FilePath -> IO [FilePath] immediateSubdirectories root relativeDir = do@@ -124,5 +324,27 @@       ( \entry -> do           isDirectory <- doesDirectoryExist (root </> relativeDir </> entry)           pure [entry | isDirectory]+      )+      entries++-- | The directory's immediate non-concept files, for the @# Files@ section.+--+-- Every @.md@ file is excluded rather than only the concepts: a concept has its+-- own typed section and @index.md@ and @log.md@ are reserved, so listing any of+-- the three here would duplicate or clutter. A name beginning with @.@ is+-- skipped so a stray @.DS_Store@ never lands in a committed index.+immediateFiles :: FilePath -> FilePath -> IO [FilePath]+immediateFiles root relativeDir = do+  entries <- List.sort <$> listDirectory (root </> relativeDir)+  fmap concat $+    mapM+      ( \entry -> do+          isDirectory <- doesDirectoryExist (root </> relativeDir </> entry)+          pure+            [ entry+            | not isDirectory,+              FilePath.takeExtension entry /= ".md",+              not ("." `List.isPrefixOf` entry)+            ]       )       entries

@@ -17,6 +17,7 @@ import Data.Char qualified as Char import Data.Text qualified as Text import Data.Time (Day, defaultTimeLocale, parseTimeM)+import Okf.Markdown (markdownOptions) import Okf.Prelude  -- | One parsed @log.md@ file.@@ -58,7 +59,7 @@   finish (foldl' step emptyBuild topLevelNodes)   where     topLevelNodes =-      case CMarkGFM.commonmarkToNode [] [] markdown of+      case CMarkGFM.commonmarkToNode markdownOptions [] markdown of         CMarkGFM.Node _ _ documentChildren -> documentChildren  -- | Render a log deterministically with a trailing newline.

@@ -0,0 +1,255 @@+-- | The CommonMark configuration okf parses every body with, footnote label+-- extraction for OKF v0.2 per-claim attribution, and the @# Computation@ body+-- section of an OKF v0.2 attested computation.+module Okf.Markdown+  ( markdownOptions,+    FootnoteLabels (..),+    extractFootnoteLabels,+    footnoteLabelsUsed,+    computationBlocks,+  )+where++import CMarkGFM qualified+import Control.Monad (guard)+import Data.ByteString (ByteString)+import Data.ByteString qualified as ByteString+import Data.ByteString.Char8 qualified as ByteString.Char8+import Data.List qualified as List+import Data.Text qualified as Text+import Data.Text.Encoding qualified as Text.Encoding+import Data.Word (Word8)+import Okf.Prelude++-- | The CommonMark options okf parses every body with.+--+-- Footnotes are enabled because specification §5.1 attributes a claim with a+-- markdown footnote whose label is a @sources[].id@, so footnote syntax must+-- parse as a footnote rather than as prose. Leaving them off is not neutral: a+-- single-token definition such as @[^src]: doc@ is otherwise read as a+-- CommonMark /link reference definition/ with destination @doc@, which turns its+-- citation into a phantom link that "Okf.Graph" extracts and validation then+-- reports as dangling.+--+-- The cost, accepted deliberately, is that cmark-gfm deletes a footnote+-- definition nothing cites, so Markdown links inside such a definition no longer+-- reach the concept graph.+--+-- Extensions stay per call site. They are not uniform: @schemaSectionColumns@ in+-- "Okf.Profile" needs @extTable@ to read a GitHub-flavored table, and the other+-- call sites read neither tables nor any other extension construct.+markdownOptions :: [CMarkGFM.CMarkOption]+markdownOptions = [CMarkGFM.optFootnotes]++-- | The literal contents of every code block in the first @# Computation@+-- section of a body, in document order.+--+-- A /section/ runs from a heading whose text is @computation@, trimmed and+-- compared case-insensitively, to the next heading at the same or a shallower+-- level, or to the end of the document. CommonMark makes every heading and block+-- a sibling, so the boundary is drawn here rather than read off the tree.+-- @schemaSectionColumns@ in "Okf.Profile" is the neighbouring inspector and does+-- /not/ bound its section, which is tolerable for asking whether a schema table+-- exists and is not tolerable here: specification §10.3 counts computations, and+-- a fenced block under a later @# Notes@ heading is not a second one.+--+-- Both spellings of a code block count. Specification §10.3 says "a single+-- fenced code block" and §10.2's own worked example writes an indented one;+-- cmark-gfm reports both as @CODE_BLOCK@ and the tolerant reading is the only+-- one that does not report the specification's own example as broken.+--+-- Unlike 'extractFootnoteLabels' this reads the parse tree rather than the+-- source text, and that is deliberate rather than an oversight of+-- @docs\/adr\/9-one-markdown-parse-configuration-and-source-scanned-authoring-checks.md@.+-- That record's rule is that a check catching an author's /mistake/ must read+-- what the author wrote, because the tree erases unresolvable syntax. "Is there+-- a code block under this heading" is a question about structure, which is+-- exactly what the tree records. The one erasure that reaches this function is+-- the ADR's accepted cost: a code block inside a footnote definition nothing+-- cites is deleted along with its definition, so it is invisible here.+computationBlocks :: Text -> [Text]+computationBlocks markdown =+  let CMarkGFM.Node _ _ topLevel = CMarkGFM.commonmarkToNode markdownOptions [] markdown+   in case dropWhile (not . isComputationHeading) topLevel of+        (CMarkGFM.Node _ (CMarkGFM.HEADING level) _ : rest) ->+          codeBlockLiterals (takeWhile (not . closesSection level) rest)+        _ -> []+  where+    isComputationHeading (CMarkGFM.Node _ (CMarkGFM.HEADING _) inner) =+      Text.toLower (Text.strip (inlineText inner)) == "computation"+    isComputationHeading _ = False++    -- A smaller level is a shallower heading, so @## @ inside a @# @ section+    -- keeps the section open and the next @# @ closes it.+    closesSection level (CMarkGFM.Node _ (CMarkGFM.HEADING other) _) = other <= level+    closesSection _ _ = False++    codeBlockLiterals nodes =+      [literal | CMarkGFM.Node _ (CMarkGFM.CODE_BLOCK _ literal) _ <- nodes]++-- | Concatenate all @TEXT@ and @CODE@ literals under a node list, recursively.+inlineText :: [CMarkGFM.Node] -> Text+inlineText = foldMap go+  where+    go (CMarkGFM.Node _ (CMarkGFM.TEXT literal) _) = literal+    go (CMarkGFM.Node _ (CMarkGFM.CODE literal) _) = literal+    go (CMarkGFM.Node _ _ inner) = inlineText inner++-- | The footnote labels a concept body uses, split by how it uses them.+--+-- A body may cite @[^x]@ without defining it, or define @[^x]:@ without citing+-- it, and the two mean different things to an author. For attribution both count+-- as "this document names source @x@", which is what 'footnoteLabelsUsed'+-- returns.+--+-- Labels appear in document order with duplicates removed, so that diagnostics+-- built from them are deterministic.+data FootnoteLabels = FootnoteLabels+  { footnoteReferences :: ![Text],+    footnoteDefinitions :: ![Text]+  }+  deriving stock (Generic, Eq, Show)++-- | Every label the body uses, references and definitions together, in document+-- order with duplicates removed.+footnoteLabelsUsed :: FootnoteLabels -> [Text]+footnoteLabelsUsed FootnoteLabels {footnoteReferences, footnoteDefinitions} =+  List.nub (footnoteReferences <> footnoteDefinitions)++-- | Extract footnote labels from a concept body.+--+-- This reads the body's __source text__ and uses the parse tree only to find the+-- regions that are code. It does not walk the tree for footnote nodes, and that+-- is deliberate rather than a shortcut: cmark-gfm reverts a citation with no+-- matching definition to plain text and deletes a definition nothing cites, so+-- the tree exposes only labels that are already internally consistent. The two+-- mistakes attribution checking exists to catch — a mistyped citation and an+-- uncited definition — are exactly the two the tree erases.+--+-- Scanning source text alone would match footnote syntax inside code, so the+-- parse supplies the exclusions. One narrow gap follows from parsing with+-- footnotes enabled: a fenced code block nested inside a footnote definition+-- that nothing cites is deleted along with its definition, so text inside it is+-- scanned. That costs a spurious label in a document that already has an uncited+-- definition.+extractFootnoteLabels :: Text -> FootnoteLabels+extractFootnoteLabels markdown =+  FootnoteLabels+    { footnoteReferences = List.nub (foldMap fst scanned),+      footnoteDefinitions = List.nub (foldMap snd scanned)+    }+  where+    scanned = zipWith scanLine [1 ..] (Text.lines markdown)+    isCode = codeRegionTest markdown++    scanLine lineNumber lineText =+      let bytes = Text.Encoding.encodeUtf8 lineText+          inCode = isCode lineNumber+       in case definitionAt bytes of+            Just (label, afterColon)+              | not (inCode (indentColumn bytes)) ->+                  (references inCode bytes afterColon, [label])+            _ -> (references inCode bytes 0, [])++-- | The 1-based byte column at which a line's content starts.+indentColumn :: ByteString -> Int+indentColumn bytes =+  ByteString.length (ByteString.Char8.takeWhile (== ' ') bytes) + 1++-- | A footnote definition opens a line: at most three spaces of indentation,+-- then @[^label]:@. Returns the label and the byte offset just past the colon,+-- so the rest of the line can still be scanned for citations.+definitionAt :: ByteString -> Maybe (Text, Int)+definitionAt bytes = do+  let indent = indentColumn bytes - 1+  guard (indent <= 3)+  (label, afterBracket) <- labelAt bytes indent+  guard (ByteString.indexMaybe bytes afterBracket == Just colon)+  pure (label, afterBracket + 1)++-- | Every @[^label]@ citation on one line from the given byte offset onwards,+-- skipping any that falls inside code and any that is backslash-escaped.+references :: (Int -> Bool) -> ByteString -> Int -> [Text]+references inCode bytes = go+  where+    go offset =+      case ByteString.Char8.elemIndex '[' (ByteString.drop offset bytes) of+        Nothing -> []+        Just relative ->+          let start = offset + relative+           in case labelAt bytes start of+                Just (label, afterBracket)+                  | not (escapedAt start),+                    not (inCode (start + 1)) ->+                      label : go afterBracket+                Just (_, afterBracket) -> go afterBracket+                Nothing -> go (start + 1)++    escapedAt start =+      start > 0 && ByteString.indexMaybe bytes (start - 1) == Just backslash++-- | Match @[^label]@ starting at a byte offset, returning the label and the+-- offset just past the closing bracket.+--+-- A label is one or more bytes that are none of whitespace, @[@, or @]@, which+-- is close enough to cmark-gfm's own rule for this purpose: the parser rejects+-- @[^has space]@ as a footnote and so does this.+labelAt :: ByteString -> Int -> Maybe (Text, Int)+labelAt bytes start = do+  guard (ByteString.indexMaybe bytes start == Just openBracket)+  guard (ByteString.indexMaybe bytes (start + 1) == Just caret)+  let label = ByteString.takeWhile isLabelByte (ByteString.drop (start + 2) bytes)+      afterLabel = start + 2 + ByteString.length label+  guard (not (ByteString.null label))+  guard (ByteString.indexMaybe bytes afterLabel == Just closeBracket)+  pure (Text.Encoding.decodeUtf8Lenient label, afterLabel + 1)+  where+    isLabelByte byte =+      byte /= openBracket+        && byte /= closeBracket+        && byte > 32+        && byte /= 127++openBracket, closeBracket, caret, colon, backslash :: Word8+openBracket = 91+closeBracket = 93+caret = 94+colon = 58+backslash = 92++-- | A region of a body that must not be scanned for footnote syntax.+data CodeRegion+  = -- | A code block, excluded by whole lines: its start and end line.+    CodeLines !Int !Int+  | -- | An inline code span, excluded by position: its start and end+    -- @(line, column)@.+    CodeSpan !(Int, Int) !(Int, Int)+  deriving stock (Generic, Eq, Show)++-- | Whether a @(line, column)@ position falls inside code.+--+-- Columns are __byte__ offsets into the line, 1-based, because that is what+-- cmark-gfm's position information reports: a line containing any multi-byte+-- character puts its later nodes at a column beyond its character count.+codeRegionTest :: Text -> (Int -> Int -> Bool)+codeRegionTest markdown = \lineNumber column ->+  any (covers lineNumber column) regions+  where+    regions = collect (CMarkGFM.commonmarkToNode markdownOptions [] markdown)++    collect (CMarkGFM.Node nodePosition nodeType childNodes) =+      case (nodeType, nodePosition) of+        (CMarkGFM.CODE_BLOCK _ _, Just posInfo) ->+          [CodeLines (CMarkGFM.startLine posInfo) (CMarkGFM.endLine posInfo)]+        (CMarkGFM.CODE _, Just posInfo) ->+          [ CodeSpan+              (CMarkGFM.startLine posInfo, CMarkGFM.startColumn posInfo)+              (CMarkGFM.endLine posInfo, CMarkGFM.endColumn posInfo)+          ]+        _ -> foldMap collect childNodes++    covers lineNumber column = \case+      CodeLines firstLine lastLine ->+        lineNumber >= firstLine && lineNumber <= lastLine+      CodeSpan spanStart spanEnd ->+        (lineNumber, column) >= spanStart && (lineNumber, column) <= spanEnd

@@ -0,0 +1,141 @@+-- | The OKF v0.2 path-valued field grammar (specification §6.2).+--+-- Several frontmatter fields name a path or URI: @resource@,+-- @sources[].resource@, and the attested-computation fields @computation@,+-- @executor.resource@, and @attester.resource@. Each accepts an absolute URL, a+-- bundle-relative path beginning with @\/@, or an ordinary relative path.+--+-- Classification is total and offline: it never touches the filesystem and never+-- decides whether a target exists. Deciding that is the caller's job, because+-- what counts as existing depends on what the caller can see. 'Okf.Profile'+-- resolves only @.md@ targets, because it is handed a list of concepts and+-- nothing else.+--+-- Deliberately distinct from 'Okf.Graph.extractConceptLinks', which reads+-- Markdown links out of a concept /body/ and is free to drop anything it does+-- not recognize. A path-valued /field/ is something the author wrote on purpose,+-- so every shape it can take is named here rather than silently ignored.+module Okf.Path+  ( PathReference (..),+    classifyPathReference,+    collapseBundlePath,+    PathResolution (..),+    resolvePathReference,+  )+where++import Control.Monad (foldM)+import Data.Text qualified as Text+import Network.URI (parseURI, uriScheme)+import Okf.ConceptId (ConceptId, conceptIdToFilePath)+import Okf.Prelude+import System.FilePath ((</>))+import System.FilePath qualified as FilePath++-- | What one raw path-valued frontmatter value turned out to be.+data PathReference+  = -- | An absolute URL, carrying its case-folded scheme.+    ExternalUrl !Text+  | -- | A path inside the bundle, collapsed and expressed relative to the+    -- bundle root, with any fragment or query suffix removed.+    BundlePath !FilePath+  | -- | A relative path that climbs above the bundle root.+    EscapesBundle+  | -- | Text that is neither: empty, whitespace, or otherwise unusable.+    MalformedPath+  deriving stock (Generic, Eq, Ord, Show)++-- | Classify one raw value written on the given concept. A relative path is+-- resolved against the concept's own directory, matching how a Markdown link in+-- that concept's body resolves; a value beginning with @\/@ resolves from the+-- bundle root regardless of where the concept lives.+--+-- An absolute URL is recognized by having a URI scheme, so this accepts every+-- scheme rather than the three 'Okf.Graph' treats as external. Whether a given+-- scheme is /permitted/ is a profile question and is decided by the caller.+classifyPathReference :: ConceptId -> Text -> PathReference+classifyPathReference sourceConcept rawValue+  | Text.null trimmed = MalformedPath+  | Just scheme <- absoluteUrlScheme trimmed = ExternalUrl scheme+  | Text.null cleanText = MalformedPath+  | otherwise =+      case collapseBundlePath candidatePath of+        Nothing -> EscapesBundle+        Just [] -> MalformedPath+        Just collapsed -> BundlePath collapsed+  where+    trimmed = Text.strip rawValue+    cleanText = stripUrlSuffix trimmed+    cleanPath = Text.unpack cleanText+    sourceDirectory = FilePath.takeDirectory (conceptIdToFilePath sourceConcept)+    candidatePath+      | "/" `Text.isPrefixOf` cleanText = dropWhile (== '/') cleanPath+      | otherwise = sourceDirectory </> cleanPath++-- | The outcome of resolving a path-valued frontmatter field against a bundle:+-- 'classifyPathReference' plus the one question it deliberately does not answer.+data PathResolution+  = -- | An absolute URL, carrying its case-folded scheme. okf never fetches it,+    -- so this is as resolved as an external target gets.+    ResolvedExternal !Text+  | -- | Names a file the bundle contains, at the given bundle-relative path.+    ResolvedInBundle !FilePath+  | -- | Looks exactly like a bundle path, and the bundle holds no such file.+    DanglingInBundle !FilePath+  | -- | Climbs above the bundle root, so there is nothing in the bundle it+    -- could name.+    UnresolvableEscape+  | -- | Empty, whitespace, or otherwise unusable as either a URL or a path.+    UnresolvableMalformed+  deriving stock (Generic, Eq, Ord, Show)++-- | Resolve one raw path-valued value written on the given concept, asking the+-- supplied predicate whether a bundle-relative path names a file that exists.+--+-- The predicate is a plain function rather than a bundle type so that this+-- module stays below 'Okf.Bundle' in the import graph; a caller holding a+-- 'Okf.Bundle.BundleInventory' passes+-- @flip Okf.Bundle.bundleInventoryMember inventory@.+--+-- Deliberately a thin composition over 'classifyPathReference'. Its value is+-- that the five outcomes are named once, so every caller agrees on what they+-- mean — in particular that an external URL is /resolved/ rather than skipped,+-- and that a path which escapes the bundle is a different finding from one that+-- simply is not there.+resolvePathReference :: (FilePath -> Bool) -> ConceptId -> Text -> PathResolution+resolvePathReference exists sourceConcept rawValue =+  case classifyPathReference sourceConcept rawValue of+    ExternalUrl scheme -> ResolvedExternal scheme+    BundlePath target+      | exists target -> ResolvedInBundle target+      | otherwise -> DanglingInBundle target+    EscapesBundle -> UnresolvableEscape+    MalformedPath -> UnresolvableMalformed++-- | The case-folded scheme of an absolute URL, or 'Nothing' for anything that+-- is not one. A bundle-absolute path such as @\/references\/policy.md@ has no+-- scheme and so is never mistaken for a URL.+absoluteUrlScheme :: Text -> Maybe Text+absoluteUrlScheme rawValue = do+  parsed <- parseURI (Text.unpack rawValue)+  let scheme = Text.toCaseFold (Text.dropWhileEnd (== ':') (Text.pack (uriScheme parsed)))+  if Text.null scheme then Nothing else Just scheme++-- | Fold @.@ and @..@ segments, returning 'Nothing' for a path that climbs above+-- the bundle root. Exported because resolving a bundle-relative path is the same+-- operation wherever it is done, and a second copy would be free to drift.+collapseBundlePath :: FilePath -> Maybe FilePath+collapseBundlePath =+  fmap FilePath.joinPath . foldM step [] . FilePath.splitDirectories+  where+    step [] "." = Just []+    step acc "." = Just acc+    step [] ".." = Nothing+    step acc ".." = Just (init acc)+    step acc segment = Just (acc <> [segment])++-- | Drop a URL fragment or query suffix, so @policy.md#section@ resolves to the+-- same target as @policy.md@.+stripUrlSuffix :: Text -> Text+stripUrlSuffix =+  Text.takeWhile (\character -> character /= '#' && character /= '?')

@@ -15,2486 +15,3909 @@     FrontmatterRules (..),     FieldCondition (..),     HandleReferenceRule (..),-    FieldRule (..),-    NestedRules (..),-    NestedFieldRule (..),-    Cardinality (..),-    FieldFormat (..),-    TypeRule (..),-    FieldPath (..),-    FieldPathSegment (..),-    loadProfileFile,-    decodeProfileExpr,-    profileFieldDescription,-    CompiledProfile,-    ProfileDefinitionError (..),-    compileProfile,-    compiledProfileSpec,-    profileFieldDescriptionForType,--    -- * Validation-    DocumentId (..),-    parseDocumentId,-    renderDocumentId,-    documentIdsInBundle,-    nextDocumentId,-    ProfileViolation (..),-    validateProfile,--    -- * Body inspection-    schemaSectionColumns,-  )-where--import CMarkGFM qualified-import Control.Exception (SomeException, catch)-import Data.Aeson (ToJSON (..), object, (.=))-import Data.Aeson.Key qualified as Aeson.Key-import Data.Aeson.KeyMap qualified as Aeson.KeyMap-import Data.Char (isAsciiLower, isAsciiUpper)-import Data.List qualified as List-import Data.Map.Strict (Map)-import Data.Map.Strict qualified as Map-import Data.Maybe (mapMaybe)-import Data.Set qualified as Set-import Data.Text qualified as Text-import Data.Text.Read qualified as Text.Read-import Data.Time.Calendar (Day)-import Data.Time.Clock (UTCTime)-import Data.Time.Format.ISO8601 (iso8601ParseM)-import Data.Vector qualified as Vector-import Data.Void (Void)-import Dhall (FromDhall (..), auto, genericAutoWith)-import Dhall qualified-import Dhall.Core (Expr)-import Dhall.Src (Src)-import Network.URI (parseURI, uriScheme)-import Numeric.Natural (Natural)-import Okf.Bundle-  ( Concept,-    conceptDocument,-    conceptIdOf,-    conceptResource,-    conceptType,-  )-import Okf.ConceptId (ConceptId, renderConceptId)-import Okf.Document (Frontmatter, coreFrontmatterFields, frontmatterKeys, frontmatterLookup)-import Okf.Prelude hiding (List, (.=))-import Okf.Validation (ValidationProfile (..))-import "generic-lens" Data.Generics.Labels ()---- | A complete house profile. @description@ is prose documenting the profile as--- a whole; like every description in this module it is never checked against a--- bundle and can never produce a 'ProfileViolation'.-data ProfileSpec = ProfileSpec-  { name :: !Text,-    description :: !(Maybe Text),-    okfVersion :: !Text,-    frontmatter :: !FrontmatterRules,-    allowUnknownTypes :: !Bool,-    allowUnknownFields :: !Bool,-    idField :: !(Maybe Text),-    types :: ![TypeRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)---- | Frontmatter keys the profile expects on every concept. @required@ is always--- checked, @recommended@ only under 'StrictAuthoring', and @optional@ never:--- an optional key is fully validated whenever it is present and its absence is--- never a deviation in any mode.-data FrontmatterRules = FrontmatterRules-  { required :: ![FieldRule],-    recommended :: ![FieldRule],-    optional :: ![FieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)---- | A same-scope predicate controlling whether a field's presence rule applies.--- The source field must compile to a closed scalar textual vocabulary.-data FieldCondition = FieldCondition-  { field :: !Text,-    hasValue :: ![Text]-  }-  deriving stock (Generic, Eq, Ord, Show)-  deriving anyclass (FromDhall)---- | A top-level field whose textual values point either to a local document--- handle with one prefix or to an absolute URI with an explicitly allowed--- scheme. External targets are never resolved by okf.-data HandleReferenceRule = HandleReferenceRule-  { localPrefix :: !Text,-    externalUriSchemes :: ![Text],-    allowSelf :: !Bool-  }-  deriving stock (Generic, Eq, Ord, Show)-  deriving anyclass (FromDhall)---- | One documented frontmatter key. The description is prose for humans and is--- never checked against a bundle.-data FieldRule = FieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality,-    format :: !(Maybe FieldFormat),-    elementFields :: !(Maybe NestedRules),-    reference :: !(Maybe HandleReferenceRule),-    when :: !(Maybe FieldCondition)-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)---- | Rules for the flat object stored in each element of a list-valued field.--- The nested rule type has no @elementFields@ member, which makes the public--- descriptor depth-bounded rather than recursive.-data NestedRules = NestedRules-  { required :: ![NestedFieldRule],-    recommended :: ![NestedFieldRule],-    optional :: ![NestedFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data NestedFieldRule = NestedFieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality,-    format :: !(Maybe FieldFormat),-    when :: !(Maybe FieldCondition)-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data Cardinality = Any | Scalar | List-  deriving stock (Generic, Eq, Ord, Show)-  deriving anyclass (FromDhall)---- | A named textual format. Formats constrain present text values but do not--- imply that a field must be present.-data FieldFormat-  = Rfc3339Utc-  | Date-  | Uri-  | UriWithScheme Text-  | DocumentHandle Text-  deriving stock (Generic, Eq, Ord, Show)-  deriving anyclass (FromDhall)---- | One rule per allowed concept @type@ string.-data TypeRule = TypeRule-  { type_ :: !Text,-    description :: !(Maybe Text),-    frontmatter :: !FrontmatterRules,-    pathPattern :: !(Maybe Text),-    resourceScheme :: !(Maybe Text),-    requireSchemaSection :: !Bool,-    schemaColumns :: ![Text],-    idPrefix :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)---- | Decode @type_@ from the Dhall field @type@ by stripping the trailing--- underscore; all other fields map by their exact name. (Mirrors how--- 'Okf.Bundle' uses a @type_@ field to avoid clashing with the @type@ keyword.)-instance FromDhall TypeRule where-  autoWith _normalizer =-    genericAutoWith-      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})-    where-      stripTrailingUnderscore fieldName =-        fromMaybe fieldName (Text.stripSuffix "_" fieldName)---- | Encode a profile so tooling can consume the same descriptor okf reads.--- Written by hand rather than derived so the key order is stable and, more--- importantly, so 'TypeRule' emits @type@ rather than the Haskell field name--- @type_@ — matching the Dhall field and how 'Okf.Graph.Node' already encodes.-instance ToJSON ProfileSpec where-  toJSON ProfileSpec {name, description, okfVersion, frontmatter, allowUnknownTypes, allowUnknownFields, idField, types = typeRules} =-    object-      [ "name" .= name,-        "description" .= description,-        "okfVersion" .= okfVersion,-        "allowUnknownTypes" .= allowUnknownTypes,-        "allowUnknownFields" .= allowUnknownFields,-        "idField" .= idField,-        "frontmatter" .= frontmatter,-        "types" .= typeRules-      ]--instance ToJSON FrontmatterRules where-  toJSON FrontmatterRules {required, recommended, optional} =-    object-      [ "required" .= required,-        "recommended" .= recommended,-        "optional" .= optional-      ]--instance ToJSON FieldCondition where-  toJSON FieldCondition {field = fieldName, hasValue} =-    object-      [ "field" .= fieldName,-        "hasValue" .= hasValue-      ]--instance ToJSON HandleReferenceRule where-  toJSON HandleReferenceRule {localPrefix, externalUriSchemes, allowSelf} =-    object-      [ "localPrefix" .= localPrefix,-        "externalUriSchemes" .= externalUriSchemes,-        "allowSelf" .= allowSelf-      ]--instance ToJSON FieldRule where-  toJSON FieldRule {field = fieldName, description, allowedValues, cardinality, format, elementFields, reference, when = condition} =-    object-      [ "field" .= fieldName,-        "description" .= description,-        "allowedValues" .= allowedValues,-        "cardinality" .= cardinality,-        "format" .= format,-        "elementFields" .= elementFields,-        "reference" .= reference,-        "when" .= condition-      ]--instance ToJSON NestedRules where-  toJSON NestedRules {required, recommended, optional} =-    object-      [ "required" .= required,-        "recommended" .= recommended,-        "optional" .= optional-      ]--instance ToJSON NestedFieldRule where-  toJSON NestedFieldRule {field = fieldName, description, allowedValues, cardinality, format, when = condition} =-    object-      [ "field" .= fieldName,-        "description" .= description,-        "allowedValues" .= allowedValues,-        "cardinality" .= cardinality,-        "format" .= format,-        "when" .= condition-      ]--instance ToJSON Cardinality where-  toJSON = String . cardinalityName--cardinalityName :: Cardinality -> Text-cardinalityName = \case-  Any -> "any"-  Scalar -> "scalar"-  List -> "list"--instance ToJSON FieldFormat where-  toJSON = \case-    Rfc3339Utc -> String "rfc3339-utc"-    Date -> String "date"-    Uri -> String "uri"-    UriWithScheme scheme -> object ["uriWithScheme" .= scheme]-    DocumentHandle prefix -> object ["documentHandle" .= prefix]--instance ToJSON TypeRule where-  toJSON-    TypeRule-      { type_ = ruleType,-        description,-        frontmatter,-        pathPattern,-        resourceScheme,-        requireSchemaSection,-        schemaColumns,-        idPrefix-      } =-      object-        [ "type" .= ruleType,-          "description" .= description,-          "frontmatter" .= frontmatter,-          "pathPattern" .= pathPattern,-          "resourceScheme" .= resourceScheme,-          "requireSchemaSection" .= requireSchemaSection,-          "schemaColumns" .= schemaColumns,-          "idPrefix" .= idPrefix-        ]---- | The okf 0.2.x profile record: frontmatter keys were bare strings and--- nothing carried a description. Decoded only as a fallback, so descriptors--- written before descriptions existed keep loading unchanged. Deliberately--- private and deliberately frozen — it is a record of a retired shape, not a--- second profile model. Exercised by--- @okf-core\/test\/fixtures\/profiles\/legacy-0.2.dhall@.-data LegacyProfileSpec = LegacyProfileSpec-  { name :: !Text,-    okfVersion :: !Text,-    frontmatter :: !LegacyFrontmatterRules,-    allowUnknownTypes :: !Bool,-    idField :: !(Maybe Text),-    types :: ![LegacyTypeRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)---- | The okf 0.2.x frontmatter record: two lists of bare key names.-data LegacyFrontmatterRules = LegacyFrontmatterRules-  { required :: ![Text],-    recommended :: ![Text]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)---- | The okf 0.2.x per-@type@ rule: today's 'TypeRule' without descriptions or--- type-specific frontmatter.-data LegacyTypeRule = LegacyTypeRule-  { type_ :: !Text,-    pathPattern :: !(Maybe Text),-    resourceScheme :: !(Maybe Text),-    requireSchemaSection :: !Bool,-    schemaColumns :: ![Text],-    idPrefix :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)--instance FromDhall LegacyTypeRule where-  autoWith _normalizer =-    genericAutoWith-      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})-    where-      stripTrailingUnderscore fieldName =-        fromMaybe fieldName (Text.stripSuffix "_" fieldName)---- | The complete reference-aware descriptor generation, frozen before the--- @optional@ presence list was added to 'FrontmatterRules' and 'NestedRules'.--- This is the immediately preceding public descriptor generation: it matches--- today's shape exactly apart from that third list, so every descriptor written--- as a record literal against the published schema keeps loading. Exercised by--- @okf-core\/test\/fixtures\/profiles\/document-references-ep3.dhall@.-data ReferenceProfileFieldRule = ReferenceProfileFieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality,-    format :: !(Maybe FieldFormat),-    elementFields :: !(Maybe ReferenceProfileNestedRules),-    reference :: !(Maybe HandleReferenceRule),-    when :: !(Maybe FieldCondition)-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data ReferenceProfileNestedRules = ReferenceProfileNestedRules-  { required :: ![ReferenceProfileNestedFieldRule],-    recommended :: ![ReferenceProfileNestedFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data ReferenceProfileNestedFieldRule = ReferenceProfileNestedFieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality,-    format :: !(Maybe FieldFormat),-    when :: !(Maybe FieldCondition)-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data ReferenceProfileFrontmatterRules = ReferenceProfileFrontmatterRules-  { required :: ![ReferenceProfileFieldRule],-    recommended :: ![ReferenceProfileFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data ReferenceProfileSpec = ReferenceProfileSpec-  { name :: !Text,-    description :: !(Maybe Text),-    okfVersion :: !Text,-    frontmatter :: !ReferenceProfileFrontmatterRules,-    allowUnknownTypes :: !Bool,-    allowUnknownFields :: !Bool,-    idField :: !(Maybe Text),-    types :: ![ReferenceProfileTypeRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data ReferenceProfileTypeRule = ReferenceProfileTypeRule-  { type_ :: !Text,-    description :: !(Maybe Text),-    frontmatter :: !ReferenceProfileFrontmatterRules,-    pathPattern :: !(Maybe Text),-    resourceScheme :: !(Maybe Text),-    requireSchemaSection :: !Bool,-    schemaColumns :: ![Text],-    idPrefix :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)--instance FromDhall ReferenceProfileTypeRule where-  autoWith _normalizer =-    genericAutoWith-      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})-    where-      stripTrailingUnderscore fieldName =-        fromMaybe fieldName (Text.stripSuffix "_" fieldName)---- | The complete condition-aware descriptor generation, frozen before--- top-level document-reference policies were added.-data ConditionalProfileFieldRule = ConditionalProfileFieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality,-    format :: !(Maybe FieldFormat),-    elementFields :: !(Maybe ConditionalProfileNestedRules),-    when :: !(Maybe FieldCondition)-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data ConditionalProfileNestedRules = ConditionalProfileNestedRules-  { required :: ![ConditionalProfileNestedFieldRule],-    recommended :: ![ConditionalProfileNestedFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data ConditionalProfileNestedFieldRule = ConditionalProfileNestedFieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality,-    format :: !(Maybe FieldFormat),-    when :: !(Maybe FieldCondition)-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data ConditionalProfileFrontmatterRules = ConditionalProfileFrontmatterRules-  { required :: ![ConditionalProfileFieldRule],-    recommended :: ![ConditionalProfileFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data ConditionalProfileSpec = ConditionalProfileSpec-  { name :: !Text,-    description :: !(Maybe Text),-    okfVersion :: !Text,-    frontmatter :: !ConditionalProfileFrontmatterRules,-    allowUnknownTypes :: !Bool,-    allowUnknownFields :: !Bool,-    idField :: !(Maybe Text),-    types :: ![ConditionalProfileTypeRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data ConditionalProfileTypeRule = ConditionalProfileTypeRule-  { type_ :: !Text,-    description :: !(Maybe Text),-    frontmatter :: !ConditionalProfileFrontmatterRules,-    pathPattern :: !(Maybe Text),-    resourceScheme :: !(Maybe Text),-    requireSchemaSection :: !Bool,-    schemaColumns :: ![Text],-    idPrefix :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)--instance FromDhall ConditionalProfileTypeRule where-  autoWith _normalizer =-    genericAutoWith-      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})-    where-      stripTrailingUnderscore fieldName =-        fromMaybe fieldName (Text.stripSuffix "_" fieldName)---- | The complete bounded-nested descriptor generation, frozen before--- same-scope field conditions were added. This is the immediately preceding--- public descriptor generation.-data NestedProfileFieldRule = NestedProfileFieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality,-    format :: !(Maybe FieldFormat),-    elementFields :: !(Maybe NestedProfileRules)-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data NestedProfileRules = NestedProfileRules-  { required :: ![NestedProfileNestedFieldRule],-    recommended :: ![NestedProfileNestedFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data NestedProfileNestedFieldRule = NestedProfileNestedFieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality,-    format :: !(Maybe FieldFormat)-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data NestedProfileFrontmatterRules = NestedProfileFrontmatterRules-  { required :: ![NestedProfileFieldRule],-    recommended :: ![NestedProfileFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data NestedProfileSpec = NestedProfileSpec-  { name :: !Text,-    description :: !(Maybe Text),-    okfVersion :: !Text,-    frontmatter :: !NestedProfileFrontmatterRules,-    allowUnknownTypes :: !Bool,-    allowUnknownFields :: !Bool,-    idField :: !(Maybe Text),-    types :: ![NestedProfileTypeRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data NestedProfileTypeRule = NestedProfileTypeRule-  { type_ :: !Text,-    description :: !(Maybe Text),-    frontmatter :: !NestedProfileFrontmatterRules,-    pathPattern :: !(Maybe Text),-    resourceScheme :: !(Maybe Text),-    requireSchemaSection :: !Bool,-    schemaColumns :: ![Text],-    idPrefix :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)--instance FromDhall NestedProfileTypeRule where-  autoWith _normalizer =-    genericAutoWith-      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})-    where-      stripTrailingUnderscore fieldName =-        fromMaybe fieldName (Text.stripSuffix "_" fieldName)---- | The complete EP-4 field rule, frozen before one-level nested records were--- added. This is the immediately preceding public descriptor generation.-data FormatFieldRule = FormatFieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality,-    format :: !(Maybe FieldFormat)-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data FormatFrontmatterRules = FormatFrontmatterRules-  { required :: ![FormatFieldRule],-    recommended :: ![FormatFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data FormatProfileSpec = FormatProfileSpec-  { name :: !Text,-    description :: !(Maybe Text),-    okfVersion :: !Text,-    frontmatter :: !FormatFrontmatterRules,-    allowUnknownTypes :: !Bool,-    allowUnknownFields :: !Bool,-    idField :: !(Maybe Text),-    types :: ![FormatTypeRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data FormatTypeRule = FormatTypeRule-  { type_ :: !Text,-    description :: !(Maybe Text),-    frontmatter :: !FormatFrontmatterRules,-    pathPattern :: !(Maybe Text),-    resourceScheme :: !(Maybe Text),-    requireSchemaSection :: !Bool,-    schemaColumns :: ![Text],-    idPrefix :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)--instance FromDhall FormatTypeRule where-  autoWith _normalizer =-    genericAutoWith-      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})-    where-      stripTrailingUnderscore fieldName =-        fromMaybe fieldName (Text.stripSuffix "_" fieldName)---- | The EP-3 field rule, frozen before named formats were added.-data CardinalityFieldRule = CardinalityFieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data CardinalityFrontmatterRules = CardinalityFrontmatterRules-  { required :: ![CardinalityFieldRule],-    recommended :: ![CardinalityFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)---- | The complete EP-3 profile shape, frozen before named formats were added.-data CardinalityProfileSpec = CardinalityProfileSpec-  { name :: !Text,-    description :: !(Maybe Text),-    okfVersion :: !Text,-    frontmatter :: !CardinalityFrontmatterRules,-    allowUnknownTypes :: !Bool,-    allowUnknownFields :: !Bool,-    idField :: !(Maybe Text),-    types :: ![CardinalityTypeRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data CardinalityTypeRule = CardinalityTypeRule-  { type_ :: !Text,-    description :: !(Maybe Text),-    frontmatter :: !CardinalityFrontmatterRules,-    pathPattern :: !(Maybe Text),-    resourceScheme :: !(Maybe Text),-    requireSchemaSection :: !Bool,-    schemaColumns :: ![Text],-    idPrefix :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)--instance FromDhall CardinalityTypeRule where-  autoWith _normalizer =-    genericAutoWith-      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})-    where-      stripTrailingUnderscore fieldName =-        fromMaybe fieldName (Text.stripSuffix "_" fieldName)---- | The EP-2 field rule, frozen before cardinality was added.-data VocabularyFieldRule = VocabularyFieldRule-  { field :: !Text,-    description :: !(Maybe Text),-    allowedValues :: ![Text]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data VocabularyFrontmatterRules = VocabularyFrontmatterRules-  { required :: ![VocabularyFieldRule],-    recommended :: ![VocabularyFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)---- | The EP-2 profile shape, frozen before cardinality was added.-data VocabularyProfileSpec = VocabularyProfileSpec-  { name :: !Text,-    description :: !(Maybe Text),-    okfVersion :: !Text,-    frontmatter :: !VocabularyFrontmatterRules,-    allowUnknownTypes :: !Bool,-    allowUnknownFields :: !Bool,-    idField :: !(Maybe Text),-    types :: ![VocabularyTypeRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data VocabularyTypeRule = VocabularyTypeRule-  { type_ :: !Text,-    description :: !(Maybe Text),-    frontmatter :: !VocabularyFrontmatterRules,-    pathPattern :: !(Maybe Text),-    resourceScheme :: !(Maybe Text),-    requireSchemaSection :: !Bool,-    schemaColumns :: ![Text],-    idPrefix :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)--instance FromDhall VocabularyTypeRule where-  autoWith _normalizer =-    genericAutoWith-      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})-    where-      stripTrailingUnderscore fieldName =-        fromMaybe fieldName (Text.stripSuffix "_" fieldName)---- | A field rule from either self-documenting schema generation, before value--- vocabularies were added.-data PreviousFieldRule = PreviousFieldRule-  { field :: !Text,-    description :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data PreviousFrontmatterRules = PreviousFrontmatterRules-  { required :: ![PreviousFieldRule],-    recommended :: ![PreviousFieldRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)---- | The type-aware shape from EP-1, frozen before vocabularies and field-name--- closure were added.-data TypeAwareProfileSpec = TypeAwareProfileSpec-  { name :: !Text,-    description :: !(Maybe Text),-    okfVersion :: !Text,-    frontmatter :: !PreviousFrontmatterRules,-    allowUnknownTypes :: !Bool,-    idField :: !(Maybe Text),-    types :: ![TypeAwareTypeRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data TypeAwareTypeRule = TypeAwareTypeRule-  { type_ :: !Text,-    description :: !(Maybe Text),-    frontmatter :: !PreviousFrontmatterRules,-    pathPattern :: !(Maybe Text),-    resourceScheme :: !(Maybe Text),-    requireSchemaSection :: !Bool,-    schemaColumns :: ![Text],-    idPrefix :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)--instance FromDhall TypeAwareTypeRule where-  autoWith _normalizer =-    genericAutoWith-      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})-    where-      stripTrailingUnderscore fieldName =-        fromMaybe fieldName (Text.stripSuffix "_" fieldName)---- | The self-documenting profile shape published immediately before--- type-specific frontmatter rules. It is frozen as a compatibility decoder in--- exactly the same way as the older 0.2.x shape below.-data DescribedProfileSpec = DescribedProfileSpec-  { name :: !Text,-    description :: !(Maybe Text),-    okfVersion :: !Text,-    frontmatter :: !PreviousFrontmatterRules,-    allowUnknownTypes :: !Bool,-    idField :: !(Maybe Text),-    types :: ![DescribedTypeRule]-  }-  deriving stock (Generic, Eq, Show)-  deriving anyclass (FromDhall)--data DescribedTypeRule = DescribedTypeRule-  { type_ :: !Text,-    description :: !(Maybe Text),-    pathPattern :: !(Maybe Text),-    resourceScheme :: !(Maybe Text),-    requireSchemaSection :: !Bool,-    schemaColumns :: ![Text],-    idPrefix :: !(Maybe Text)-  }-  deriving stock (Generic, Eq, Show)--instance FromDhall DescribedTypeRule where-  autoWith _normalizer =-    genericAutoWith-      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})-    where-      stripTrailingUnderscore fieldName =-        fromMaybe fieldName (Text.stripSuffix "_" fieldName)--emptyFrontmatterRules :: FrontmatterRules-emptyFrontmatterRules = FrontmatterRules {required = [], recommended = [], optional = []}--upgradeReferenceProfileFrontmatter :: ReferenceProfileFrontmatterRules -> FrontmatterRules-upgradeReferenceProfileFrontmatter previous =-  FrontmatterRules-    { required = map upgradeField (previous ^. #required),-      recommended = map upgradeField (previous ^. #recommended),-      optional = []-    }-  where-    upgradeField rule =-      FieldRule-        { field = rule ^. #field,-          description = rule ^. #description,-          allowedValues = rule ^. #allowedValues,-          cardinality = rule ^. #cardinality,-          format = rule ^. #format,-          elementFields = upgradeNestedRules <$> rule ^. #elementFields,-          reference = rule ^. #reference,-          when = rule ^. #when-        }-    upgradeNestedRules rules =-      NestedRules-        { required = map upgradeNestedField (rules ^. #required),-          recommended = map upgradeNestedField (rules ^. #recommended),-          optional = []-        }-    upgradeNestedField rule =-      NestedFieldRule-        { field = rule ^. #field,-          description = rule ^. #description,-          allowedValues = rule ^. #allowedValues,-          cardinality = rule ^. #cardinality,-          format = rule ^. #format,-          when = rule ^. #when-        }--upgradePreviousFrontmatter :: PreviousFrontmatterRules -> FrontmatterRules-upgradePreviousFrontmatter previous =-  FrontmatterRules-    { required = map upgradeField (previous ^. #required),-      recommended = map upgradeField (previous ^. #recommended),-      optional = []-    }-  where-    upgradeField rule =-      FieldRule-        { field = rule ^. #field,-          description = rule ^. #description,-          allowedValues = [],-          cardinality = Any,-          format = Nothing,-          elementFields = Nothing,-          reference = Nothing,-          when = Nothing-        }--upgradeConditionalProfileFrontmatter :: ConditionalProfileFrontmatterRules -> FrontmatterRules-upgradeConditionalProfileFrontmatter previous =-  FrontmatterRules-    { required = map upgradeField (previous ^. #required),-      recommended = map upgradeField (previous ^. #recommended),-      optional = []-    }-  where-    upgradeField rule =-      FieldRule-        { field = rule ^. #field,-          description = rule ^. #description,-          allowedValues = rule ^. #allowedValues,-          cardinality = rule ^. #cardinality,-          format = rule ^. #format,-          elementFields = upgradeNestedRules <$> rule ^. #elementFields,-          reference = Nothing,-          when = rule ^. #when-        }-    upgradeNestedRules rules =-      NestedRules-        { required = map upgradeNestedField (rules ^. #required),-          recommended = map upgradeNestedField (rules ^. #recommended),-          optional = []-        }-    upgradeNestedField rule =-      NestedFieldRule-        { field = rule ^. #field,-          description = rule ^. #description,-          allowedValues = rule ^. #allowedValues,-          cardinality = rule ^. #cardinality,-          format = rule ^. #format,-          when = rule ^. #when-        }--upgradeNestedProfileFrontmatter :: NestedProfileFrontmatterRules -> FrontmatterRules-upgradeNestedProfileFrontmatter previous =-  FrontmatterRules-    { required = map upgradeField (previous ^. #required),-      recommended = map upgradeField (previous ^. #recommended),-      optional = []-    }-  where-    upgradeField rule =-      FieldRule-        { field = rule ^. #field,-          description = rule ^. #description,-          allowedValues = rule ^. #allowedValues,-          cardinality = rule ^. #cardinality,-          format = rule ^. #format,-          elementFields = upgradeNestedProfileRules <$> rule ^. #elementFields,-          reference = Nothing,-          when = Nothing-        }-    upgradeNestedProfileRules rules =-      NestedRules-        { required = map upgradeNestedField (rules ^. #required),-          recommended = map upgradeNestedField (rules ^. #recommended),-          optional = []-        }-    upgradeNestedField rule =-      NestedFieldRule-        { field = rule ^. #field,-          description = rule ^. #description,-          allowedValues = rule ^. #allowedValues,-          cardinality = rule ^. #cardinality,-          format = rule ^. #format,-          when = Nothing-        }--upgradeFormatFrontmatter :: FormatFrontmatterRules -> FrontmatterRules-upgradeFormatFrontmatter previous =-  FrontmatterRules-    { required = map upgradeField (previous ^. #required),-      recommended = map upgradeField (previous ^. #recommended),-      optional = []-    }-  where-    upgradeField rule =-      FieldRule-        { field = rule ^. #field,-          description = rule ^. #description,-          allowedValues = rule ^. #allowedValues,-          cardinality = rule ^. #cardinality,-          format = rule ^. #format,-          elementFields = Nothing,-          reference = Nothing,-          when = Nothing-        }--upgradeCardinalityFrontmatter :: CardinalityFrontmatterRules -> FrontmatterRules-upgradeCardinalityFrontmatter previous =-  FrontmatterRules-    { required = map upgradeField (previous ^. #required),-      recommended = map upgradeField (previous ^. #recommended),-      optional = []-    }-  where-    upgradeField rule =-      FieldRule-        { field = rule ^. #field,-          description = rule ^. #description,-          allowedValues = rule ^. #allowedValues,-          cardinality = rule ^. #cardinality,-          format = Nothing,-          elementFields = Nothing,-          reference = Nothing,-          when = Nothing-        }--upgradeVocabularyFrontmatter :: VocabularyFrontmatterRules -> FrontmatterRules-upgradeVocabularyFrontmatter previous =-  FrontmatterRules-    { required = map upgradeField (previous ^. #required),-      recommended = map upgradeField (previous ^. #recommended),-      optional = []-    }-  where-    upgradeField rule =-      FieldRule-        { field = rule ^. #field,-          description = rule ^. #description,-          allowedValues = rule ^. #allowedValues,-          cardinality = Any,-          format = Nothing,-          elementFields = Nothing,-          reference = Nothing,-          when = Nothing-        }--upgradeReferenceProfile :: ReferenceProfileSpec -> ProfileSpec-upgradeReferenceProfile previous =-  ProfileSpec-    { name = previous ^. #name,-      description = previous ^. #description,-      okfVersion = previous ^. #okfVersion,-      frontmatter = upgradeReferenceProfileFrontmatter (previous ^. #frontmatter),-      allowUnknownTypes = previous ^. #allowUnknownTypes,-      allowUnknownFields = previous ^. #allowUnknownFields,-      idField = previous ^. #idField,-      types = map upgradeRule (previous ^. #types)-    }-  where-    upgradeRule rule =-      TypeRule-        { type_ = rule ^. #type_,-          description = rule ^. #description,-          frontmatter = upgradeReferenceProfileFrontmatter (rule ^. #frontmatter),-          pathPattern = rule ^. #pathPattern,-          resourceScheme = rule ^. #resourceScheme,-          requireSchemaSection = rule ^. #requireSchemaSection,-          schemaColumns = rule ^. #schemaColumns,-          idPrefix = rule ^. #idPrefix-        }--upgradeConditionalProfile :: ConditionalProfileSpec -> ProfileSpec-upgradeConditionalProfile previous =-  ProfileSpec-    { name = previous ^. #name,-      description = previous ^. #description,-      okfVersion = previous ^. #okfVersion,-      frontmatter = upgradeConditionalProfileFrontmatter (previous ^. #frontmatter),-      allowUnknownTypes = previous ^. #allowUnknownTypes,-      allowUnknownFields = previous ^. #allowUnknownFields,-      idField = previous ^. #idField,-      types = map upgradeRule (previous ^. #types)-    }-  where-    upgradeRule rule =-      TypeRule-        { type_ = rule ^. #type_,-          description = rule ^. #description,-          frontmatter = upgradeConditionalProfileFrontmatter (rule ^. #frontmatter),-          pathPattern = rule ^. #pathPattern,-          resourceScheme = rule ^. #resourceScheme,-          requireSchemaSection = rule ^. #requireSchemaSection,-          schemaColumns = rule ^. #schemaColumns,-          idPrefix = rule ^. #idPrefix-        }--upgradeNestedProfile :: NestedProfileSpec -> ProfileSpec-upgradeNestedProfile previous =-  ProfileSpec-    { name = previous ^. #name,-      description = previous ^. #description,-      okfVersion = previous ^. #okfVersion,-      frontmatter = upgradeNestedProfileFrontmatter (previous ^. #frontmatter),-      allowUnknownTypes = previous ^. #allowUnknownTypes,-      allowUnknownFields = previous ^. #allowUnknownFields,-      idField = previous ^. #idField,-      types = map upgradeRule (previous ^. #types)-    }-  where-    upgradeRule rule =-      TypeRule-        { type_ = rule ^. #type_,-          description = rule ^. #description,-          frontmatter = upgradeNestedProfileFrontmatter (rule ^. #frontmatter),-          pathPattern = rule ^. #pathPattern,-          resourceScheme = rule ^. #resourceScheme,-          requireSchemaSection = rule ^. #requireSchemaSection,-          schemaColumns = rule ^. #schemaColumns,-          idPrefix = rule ^. #idPrefix-        }--upgradeFormatProfile :: FormatProfileSpec -> ProfileSpec-upgradeFormatProfile previous =-  ProfileSpec-    { name = previous ^. #name,-      description = previous ^. #description,-      okfVersion = previous ^. #okfVersion,-      frontmatter = upgradeFormatFrontmatter (previous ^. #frontmatter),-      allowUnknownTypes = previous ^. #allowUnknownTypes,-      allowUnknownFields = previous ^. #allowUnknownFields,-      idField = previous ^. #idField,-      types = map upgradeRule (previous ^. #types)-    }-  where-    upgradeRule rule =-      TypeRule-        { type_ = rule ^. #type_,-          description = rule ^. #description,-          frontmatter = upgradeFormatFrontmatter (rule ^. #frontmatter),-          pathPattern = rule ^. #pathPattern,-          resourceScheme = rule ^. #resourceScheme,-          requireSchemaSection = rule ^. #requireSchemaSection,-          schemaColumns = rule ^. #schemaColumns,-          idPrefix = rule ^. #idPrefix-        }--upgradeCardinalityProfile :: CardinalityProfileSpec -> ProfileSpec-upgradeCardinalityProfile previous =-  ProfileSpec-    { name = previous ^. #name,-      description = previous ^. #description,-      okfVersion = previous ^. #okfVersion,-      frontmatter = upgradeCardinalityFrontmatter (previous ^. #frontmatter),-      allowUnknownTypes = previous ^. #allowUnknownTypes,-      allowUnknownFields = previous ^. #allowUnknownFields,-      idField = previous ^. #idField,-      types = map upgradeRule (previous ^. #types)-    }-  where-    upgradeRule rule =-      TypeRule-        { type_ = rule ^. #type_,-          description = rule ^. #description,-          frontmatter = upgradeCardinalityFrontmatter (rule ^. #frontmatter),-          pathPattern = rule ^. #pathPattern,-          resourceScheme = rule ^. #resourceScheme,-          requireSchemaSection = rule ^. #requireSchemaSection,-          schemaColumns = rule ^. #schemaColumns,-          idPrefix = rule ^. #idPrefix-        }--upgradeVocabularyProfile :: VocabularyProfileSpec -> ProfileSpec-upgradeVocabularyProfile previous =-  ProfileSpec-    { name = previous ^. #name,-      description = previous ^. #description,-      okfVersion = previous ^. #okfVersion,-      frontmatter = upgradeVocabularyFrontmatter (previous ^. #frontmatter),-      allowUnknownTypes = previous ^. #allowUnknownTypes,-      allowUnknownFields = previous ^. #allowUnknownFields,-      idField = previous ^. #idField,-      types = map upgradeRule (previous ^. #types)-    }-  where-    upgradeRule rule =-      TypeRule-        { type_ = rule ^. #type_,-          description = rule ^. #description,-          frontmatter = upgradeVocabularyFrontmatter (rule ^. #frontmatter),-          pathPattern = rule ^. #pathPattern,-          resourceScheme = rule ^. #resourceScheme,-          requireSchemaSection = rule ^. #requireSchemaSection,-          schemaColumns = rule ^. #schemaColumns,-          idPrefix = rule ^. #idPrefix-        }--upgradeTypeAwareProfile :: TypeAwareProfileSpec -> ProfileSpec-upgradeTypeAwareProfile previous =-  ProfileSpec-    { name = previous ^. #name,-      description = previous ^. #description,-      okfVersion = previous ^. #okfVersion,-      frontmatter = upgradePreviousFrontmatter (previous ^. #frontmatter),-      allowUnknownTypes = previous ^. #allowUnknownTypes,-      allowUnknownFields = True,-      idField = previous ^. #idField,-      types = map upgradeRule (previous ^. #types)-    }-  where-    upgradeRule rule =-      TypeRule-        { type_ = rule ^. #type_,-          description = rule ^. #description,-          frontmatter = upgradePreviousFrontmatter (rule ^. #frontmatter),-          pathPattern = rule ^. #pathPattern,-          resourceScheme = rule ^. #resourceScheme,-          requireSchemaSection = rule ^. #requireSchemaSection,-          schemaColumns = rule ^. #schemaColumns,-          idPrefix = rule ^. #idPrefix-        }--upgradeDescribedProfile :: DescribedProfileSpec -> ProfileSpec-upgradeDescribedProfile described =-  ProfileSpec-    { name = described ^. #name,-      description = described ^. #description,-      okfVersion = described ^. #okfVersion,-      frontmatter = upgradePreviousFrontmatter (described ^. #frontmatter),-      allowUnknownTypes = described ^. #allowUnknownTypes,-      allowUnknownFields = True,-      idField = described ^. #idField,-      types = map upgradeRule (described ^. #types)-    }-  where-    upgradeRule rule =-      TypeRule-        { type_ = rule ^. #type_,-          description = rule ^. #description,-          frontmatter = emptyFrontmatterRules,-          pathPattern = rule ^. #pathPattern,-          resourceScheme = rule ^. #resourceScheme,-          requireSchemaSection = rule ^. #requireSchemaSection,-          schemaColumns = rule ^. #schemaColumns,-          idPrefix = rule ^. #idPrefix-        }---- | Lift a 0.2.x profile into the current shape by attaching no descriptions--- and empty type-specific frontmatter.-upgradeLegacyProfile :: LegacyProfileSpec -> ProfileSpec-upgradeLegacyProfile legacy =-  ProfileSpec-    { name = legacy ^. #name,-      description = Nothing,-      okfVersion = legacy ^. #okfVersion,-      frontmatter =-        FrontmatterRules-          { required = map undocumented (legacy ^. #frontmatter . #required),-            recommended = map undocumented (legacy ^. #frontmatter . #recommended),-            optional = []-          },-      allowUnknownTypes = legacy ^. #allowUnknownTypes,-      allowUnknownFields = True,-      idField = legacy ^. #idField,-      types = map upgradeRule (legacy ^. #types)-    }-  where-    undocumented key = FieldRule {field = key, description = Nothing, allowedValues = [], cardinality = Any, format = Nothing, elementFields = Nothing, reference = Nothing, when = Nothing}-    upgradeRule rule =-      TypeRule-        { type_ = rule ^. #type_,-          description = Nothing,-          frontmatter = emptyFrontmatterRules,-          pathPattern = rule ^. #pathPattern,-          resourceScheme = rule ^. #resourceScheme,-          requireSchemaSection = rule ^. #requireSchemaSection,-          schemaColumns = rule ^. #schemaColumns,-          idPrefix = rule ^. #idPrefix-        }---- | Load and decode a Dhall profile descriptor from a file path. Any evaluation--- or decoding failure is captured as a human-readable 'Left'.------ The reference-aware shape, condition-aware shape, bounded-nested shape, EP-4--- format shape, EP-3 cardinality shape, EP-2 vocabulary shape, type-aware EP-1--- shape, self-documenting shape, and okf 0.2.x shape are accepted by frozen--- fallback decoders and upgraded--- with their no-op defaults. When every decoder fails, the /current/ decoder's--- error is reported.-loadProfileFile :: FilePath -> IO (Either Text ProfileSpec)-loadProfileFile path = do-  current <- tryDecode (Dhall.inputFile auto path)-  case current of-    Right spec -> pure (Right spec)-    Left currentError -> do-      referenceAware <- tryDecode (Dhall.inputFile auto path)-      case referenceAware of-        Right referenceSpec -> pure (Right (upgradeReferenceProfile referenceSpec))-        Left _referenceError -> do-          conditional <- tryDecode (Dhall.inputFile auto path)-          case conditional of-            Right conditionalSpec -> pure (Right (upgradeConditionalProfile conditionalSpec))-            Left _conditionalError -> do-              nested <- tryDecode (Dhall.inputFile auto path)-              case nested of-                Right nestedSpec -> pure (Right (upgradeNestedProfile nestedSpec))-                Left _nestedError -> do-                  formatted <- tryDecode (Dhall.inputFile auto path)-                  case formatted of-                    Right formatSpec -> pure (Right (upgradeFormatProfile formatSpec))-                    Left _formatError -> do-                      cardinality <- tryDecode (Dhall.inputFile auto path)-                      case cardinality of-                        Right cardinalitySpec -> pure (Right (upgradeCardinalityProfile cardinalitySpec))-                        Left _cardinalityError -> do-                          vocabulary <- tryDecode (Dhall.inputFile auto path)-                          case vocabulary of-                            Right vocabularySpec -> pure (Right (upgradeVocabularyProfile vocabularySpec))-                            Left _vocabularyError -> do-                              typeAware <- tryDecode (Dhall.inputFile auto path)-                              case typeAware of-                                Right typeAwareSpec -> pure (Right (upgradeTypeAwareProfile typeAwareSpec))-                                Left _typeAwareError -> do-                                  described <- tryDecode (Dhall.inputFile auto path)-                                  case described of-                                    Right describedSpec -> pure (Right (upgradeDescribedProfile describedSpec))-                                    Left _describedError -> do-                                      legacy <- tryDecode (Dhall.inputFile auto path)-                                      pure $ case legacy of-                                        Right legacySpec -> Right (upgradeLegacyProfile legacySpec)-                                        Left _legacyError -> Left currentError-  where-    -- The ten calls look identical but are inferred at distinct result types;-    -- @auto@ picks the corresponding current or frozen decoder.-    tryDecode :: IO a -> IO (Either Text a)-    tryDecode action =-      (Right <$> action)-        `catch` \(exception :: SomeException) -> pure (Left (Text.pack (show exception)))---- | Does an already-evaluated Dhall expression decode as a profile? Tries the--- current schema, then the reference-aware, condition-aware, bounded-nested,--- EP-4, EP-3, EP-2, EP-1, self-documenting, and okf 0.2.x schemas,--- so the published @okf-profiles@ package still enumerates. Uses--- 'Dhall.rawInput', which normalizes and runs the decoder's extractor without--- throwing, which is what lets registry enumeration be pure.-decodeProfileExpr :: Expr Src Void -> Maybe ProfileSpec-decodeProfileExpr expression =-  Dhall.rawInput Dhall.auto expression-    <|> fmap upgradeReferenceProfile (Dhall.rawInput Dhall.auto expression)-    <|> fmap upgradeConditionalProfile (Dhall.rawInput Dhall.auto expression)-    <|> fmap upgradeNestedProfile (Dhall.rawInput Dhall.auto expression)-    <|> fmap upgradeFormatProfile (Dhall.rawInput Dhall.auto expression)-    <|> fmap upgradeCardinalityProfile (Dhall.rawInput Dhall.auto expression)-    <|> fmap upgradeVocabularyProfile (Dhall.rawInput Dhall.auto expression)-    <|> fmap upgradeTypeAwareProfile (Dhall.rawInput Dhall.auto expression)-    <|> fmap upgradeDescribedProfile (Dhall.rawInput Dhall.auto expression)-    <|> fmap upgradeLegacyProfile (Dhall.rawInput Dhall.auto expression)---- | The description a profile attaches to a frontmatter key, looking in--- @required@ first, then @recommended@, then @optional@. 'Nothing' when the key--- is undocumented or absent from the profile entirely.-profileFieldDescription :: ProfileSpec -> Text -> Maybe Text-profileFieldDescription spec key =-  case [rule | rule <- rules, rule ^. #field == key] of-    (rule : _) -> rule ^. #description-    [] -> Nothing-  where-    rules =-      spec ^. #frontmatter . #required-        <> spec ^. #frontmatter . #recommended-        <> spec ^. #frontmatter . #optional---- | A malformed profile definition. The optional type is absent for profile--- scope and present for a type-specific scope. The list name is @required@,--- @recommended@, or @optional@.-data ProfileDefinitionError-  = DuplicateTypeRule Text-  | DuplicateFieldRule (Maybe Text) Text Text-  | ConflictingFieldRequirement (Maybe Text) Text-  | UnsatisfiableVocabulary (Maybe Text) Text [Text] [Text]-  | ConflictingCardinality (Maybe Text) Text Cardinality Cardinality-  | ElementFieldsRequireList (Maybe Text) FieldPath Cardinality-  | InvalidFormatParameter FieldPath FieldFormat Text-  | ConflictingFieldFormat FieldPath FieldFormat FieldFormat-  | EmptyConditionValues (Maybe Text) FieldPath FieldPath-  | ConditionFieldNotDeclared (Maybe Text) FieldPath FieldPath-  | ConditionFieldNotScalar (Maybe Text) FieldPath FieldPath Cardinality-  | ConditionFieldOpenVocabulary (Maybe Text) FieldPath FieldPath-  | ConditionFieldHasUnreachableValues (Maybe Text) FieldPath FieldPath [Text] [Text]-  | SelfConditionalField (Maybe Text) FieldPath-  | InvalidReferencePrefix (Maybe Text) FieldPath Text-  | ReferencePrefixNotDeclared (Maybe Text) FieldPath Text-  | ReferenceRequiresIdField (Maybe Text) FieldPath-  | InvalidExternalReferenceScheme (Maybe Text) FieldPath Text-  | ConflictingReferencePrefix Text FieldPath Text Text-  | ReferenceWithFormat (Maybe Text) FieldPath FieldFormat-  | -- | an @optional@ rule carries a @when@ condition, which gates only presence-    -- and is therefore dead: an optional rule has no presence check at all-    OptionalFieldWithCondition (Maybe Text) FieldPath-  deriving stock (Generic, Eq, Ord, Show)--data FieldRequirement = RecommendedField | RequiredField-  deriving stock (Eq, Ord, Show)--data CompiledCondition = CompiledCondition-  { field :: !Text,-    hasValue :: ![Text]-  }-  deriving stock (Generic, Eq, Show)--data PresenceClause = PresenceClause-  { requirement :: !FieldRequirement,-    condition :: !(Maybe CompiledCondition)-  }-  deriving stock (Generic, Eq, Show)--data EffectiveFieldRule = EffectiveFieldRule-  { presenceClauses :: ![PresenceClause],-    description :: !(Maybe Text),-    allowedValues :: ![Text],-    cardinality :: !Cardinality,-    format :: !(Maybe FieldFormat),-    elementFields :: !(Maybe (Map Text EffectiveFieldRule)),-    reference :: !(Maybe HandleReferenceRule)-  }-  deriving stock (Generic, Eq, Show)---- | A raw profile whose authoring contradictions have been rejected and whose--- effective profile-plus-type frontmatter rules have been precomputed.-data CompiledProfile = CompiledProfile-  { spec :: !ProfileSpec,-    baseRules :: !(Map Text EffectiveFieldRule),-    rulesByType :: !(Map Text (Map Text EffectiveFieldRule))-  }-  deriving stock (Generic, Eq, Show)--compiledProfileSpec :: CompiledProfile -> ProfileSpec-compiledProfileSpec compiled = compiled ^. #spec--compileProfile :: ProfileSpec -> Either (NonEmpty ProfileDefinitionError) CompiledProfile-compileProfile rawSpec =-  case definitionErrors of-    firstError : remainingErrors -> Left (firstError :| remainingErrors)-    [] ->-      Right-        CompiledProfile-          { spec = rawSpec,-            baseRules,-            rulesByType =-              Map.fromList-                [ (rule ^. #type_, mergeRules baseRules (compileRules (rule ^. #frontmatter)))-                | rule <- rawSpec ^. #types-                ]-          }-  where-    baseRules = compileRules (rawSpec ^. #frontmatter)-    typeNames = map (^. #type_) (rawSpec ^. #types)-    definitionErrors =-      List.sortOn definitionErrorKey $-        map DuplicateTypeRule (duplicates typeNames)-          <> scopeErrors Nothing (rawSpec ^. #frontmatter)-          <> concat-            [ scopeErrors (Just (rule ^. #type_)) (rule ^. #frontmatter)-            | rule <- rawSpec ^. #types-            ]-          <> vocabularyErrors-          <> cardinalityErrors-          <> nestedCardinalityErrors-          <> formatParameterErrors-          <> conflictingFormatErrors-          <> conditionDefinitionErrors-          <> referenceDefinitionErrors--    definitionErrorKey = \case-      DuplicateTypeRule ctype -> (1 :: Int, ctype, 0 :: Int, "", 0 :: Int)-      DuplicateFieldRule scope listName key ->-        let (scopeRank, typeName) = scopeKey scope-         in (scopeRank, typeName, listKey listName, key, 0)-      ConflictingFieldRequirement scope key ->-        let (scopeRank, typeName) = scopeKey scope-         in (scopeRank, typeName, 2, key, 0)-      UnsatisfiableVocabulary scope key _ _ ->-        let (scopeRank, typeName) = scopeKey scope-         in (scopeRank, typeName, 3, key, 0)-      ConflictingCardinality scope key _ _ ->-        let (scopeRank, typeName) = scopeKey scope-         in (scopeRank, typeName, 4, key, 0)-      ElementFieldsRequireList scope path cardinality ->-        let (scopeRank, typeName) = scopeKey scope-         in (scopeRank, typeName, 4, renderFieldPathKey path, fromEnum (cardinality == Scalar))-      InvalidFormatParameter path fieldFormat parameter ->-        (2, renderFieldPathKey path, 5, Text.pack (show fieldFormat), Text.length parameter)-      ConflictingFieldFormat path profileFormat typeFormat ->-        (2, renderFieldPathKey path, 6, Text.pack (show profileFormat), fromEnum (profileFormat == typeFormat))-      EmptyConditionValues scope target source -> conditionErrorKey scope target source 7-      ConditionFieldNotDeclared scope target source -> conditionErrorKey scope target source 8-      ConditionFieldNotScalar scope target source cardinality ->-        let (scopeRank, typeName) = scopeKey scope-         in (scopeRank, typeName, 9, renderFieldPathKey target <> ":" <> renderFieldPathKey source, fromEnum (cardinality == Scalar))-      ConditionFieldOpenVocabulary scope target source -> conditionErrorKey scope target source 10-      ConditionFieldHasUnreachableValues scope target source _ _ -> conditionErrorKey scope target source 11-      SelfConditionalField scope target ->-        let (scopeRank, typeName) = scopeKey scope-         in (scopeRank, typeName, 12, renderFieldPathKey target, 0)-      InvalidReferencePrefix scope target prefix -> referenceErrorKey scope target 13 prefix-      ReferencePrefixNotDeclared scope target prefix -> referenceErrorKey scope target 14 prefix-      ReferenceRequiresIdField scope target -> referenceErrorKey scope target 15 ""-      InvalidExternalReferenceScheme scope target scheme -> referenceErrorKey scope target 16 scheme-      ConflictingReferencePrefix ctype target profilePrefix typePrefix ->-        (1, ctype, 17, renderFieldPathKey target <> ":" <> profilePrefix, Text.length typePrefix)-      ReferenceWithFormat scope target fieldFormat -> referenceErrorKey scope target 18 (Text.pack (show fieldFormat))-      OptionalFieldWithCondition scope target ->-        let (scopeRank, typeName) = scopeKey scope-         in (scopeRank, typeName, 19, renderFieldPathKey target, 0)--    scopeKey Nothing = (0, "")-    scopeKey (Just ctype) = (1, ctype)-    listKey "required" = 0-    listKey _ = 1-    conditionErrorKey scope target source rank =-      let (scopeRank, typeName) = scopeKey scope-       in (scopeRank, typeName, rank, renderFieldPathKey target <> ":" <> renderFieldPathKey source, 0)-    referenceErrorKey scope target rank detail =-      let (scopeRank, typeName) = scopeKey scope-       in (scopeRank, typeName, rank, renderFieldPathKey target <> ":" <> detail, 0)--    scopeErrors scope FrontmatterRules {required, recommended, optional} =-      [DuplicateFieldRule scope "required" key | key <- duplicates (map (^. #field) required)]-        <> [DuplicateFieldRule scope "recommended" key | key <- duplicates (map (^. #field) recommended)]-        <> [DuplicateFieldRule scope "optional" key | key <- duplicates (map (^. #field) optional)]-        <> [ ConflictingFieldRequirement scope key-           | key <- presenceListCollisions (map (^. #field) required) (map (^. #field) recommended) (map (^. #field) optional)-           ]-        <> concatMap (nestedScopeErrors scope) (required <> recommended <> optional)--    nestedScopeErrors scope parentRule =-      case parentRule ^. #elementFields of-        Nothing -> []-        Just NestedRules {required, recommended, optional} ->-          let qualify key = parentRule ^. #field <> "." <> key-           in [DuplicateFieldRule scope "nested required" (qualify key) | key <- duplicates (map (^. #field) required)]-                <> [DuplicateFieldRule scope "nested recommended" (qualify key) | key <- duplicates (map (^. #field) recommended)]-                <> [DuplicateFieldRule scope "nested optional" (qualify key) | key <- duplicates (map (^. #field) optional)]-                <> [ ConflictingFieldRequirement scope (qualify key)-                   | key <- presenceListCollisions (map (^. #field) required) (map (^. #field) recommended) (map (^. #field) optional)-                   ]--    -- One key classified by more than one presence list at a single scope. The-    -- profile cannot say both "always check for this" and "never check for-    -- this", so any pairing is a definition error rather than a precedence rule.-    presenceListCollisions requiredKeys recommendedKeys optionalKeys =-      List.nub . List.sort . concat $-        [ List.intersect requiredKeys recommendedKeys,-          List.intersect requiredKeys optionalKeys,-          List.intersect recommendedKeys optionalKeys-        ]--    duplicates = mapMaybe duplicateHead . List.group . List.sort-    duplicateHead (candidate : _ : _) = Just candidate-    duplicateHead _ = Nothing--    vocabularyErrors =-      [ UnsatisfiableVocabulary (Just (rule ^. #type_)) key profileValues typeValues-      | rule <- rawSpec ^. #types,-        let typeRules = compileRules (rule ^. #frontmatter),-        (key, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),-        let profileValues = profileRule ^. #allowedValues-            typeValues = typeRule ^. #allowedValues,-        not (null profileValues),-        not (null typeValues),-        null (mergeVocabulary profileValues typeValues)-      ]-        <> [ UnsatisfiableVocabulary (Just (rule ^. #type_)) (parentKey <> "." <> nestedKey) profileValues typeValues-           | rule <- rawSpec ^. #types,-             let typeRules = compileRules (rule ^. #frontmatter),-             (parentKey, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),-             Just profileNested <- [profileRule ^. #elementFields],-             Just typeNested <- [typeRule ^. #elementFields],-             (nestedKey, (profileNestedRule, typeNestedRule)) <- Map.toAscList (Map.intersectionWith (,) profileNested typeNested),-             let profileValues = profileNestedRule ^. #allowedValues-                 typeValues = typeNestedRule ^. #allowedValues,-             not (null profileValues),-             not (null typeValues),-             null (mergeVocabulary profileValues typeValues)-           ]--    cardinalityErrors =-      [ ConflictingCardinality (Just (rule ^. #type_)) key profileCardinality typeCardinality-      | rule <- rawSpec ^. #types,-        let typeRules = compileRules (rule ^. #frontmatter),-        (key, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),-        let profileCardinality = profileRule ^. #cardinality-            typeCardinality = typeRule ^. #cardinality,-        profileCardinality /= Any,-        typeCardinality /= Any,-        profileCardinality /= typeCardinality-      ]-        <> [ ConflictingCardinality (Just (rule ^. #type_)) (parentKey <> "." <> nestedKey) profileCardinality typeCardinality-           | rule <- rawSpec ^. #types,-             let typeRules = compileRules (rule ^. #frontmatter),-             (parentKey, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),-             Just profileNested <- [profileRule ^. #elementFields],-             Just typeNested <- [typeRule ^. #elementFields],-             (nestedKey, (profileNestedRule, typeNestedRule)) <- Map.toAscList (Map.intersectionWith (,) profileNested typeNested),-             let profileCardinality = profileNestedRule ^. #cardinality-                 typeCardinality = typeNestedRule ^. #cardinality,-             profileCardinality /= Any,-             typeCardinality /= Any,-             profileCardinality /= typeCardinality-           ]--    nestedCardinalityErrors =-      [ ElementFieldsRequireList scope (topLevelFieldPath (fieldRule ^. #field)) Scalar-      | (scope, rules) <- (Nothing, rawSpec ^. #frontmatter) : [(Just (rule ^. #type_), rule ^. #frontmatter) | rule <- rawSpec ^. #types],-        fieldRule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional,-        isJust (fieldRule ^. #elementFields),-        fieldRule ^. #cardinality == Scalar-      ]--    formatParameterErrors =-      [ InvalidFormatParameter (topLevelFieldPath (rule ^. #field)) fieldFormat parameter-      | rules <- (rawSpec ^. #frontmatter) : map (^. #frontmatter) (rawSpec ^. #types),-        rule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional,-        Just (fieldFormat, parameter) <- [invalidFormatParameter =<< rule ^. #format]-      ]-        <> [ InvalidFormatParameter (nestedDefinitionPath (rule ^. #field) (nestedRule ^. #field)) fieldFormat parameter-           | rules <- (rawSpec ^. #frontmatter) : map (^. #frontmatter) (rawSpec ^. #types),-             rule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional,-             Just nestedRules <- [rule ^. #elementFields],-             nestedRule <- nestedRules ^. #required <> nestedRules ^. #recommended <> nestedRules ^. #optional,-             Just (fieldFormat, parameter) <- [invalidFormatParameter =<< nestedRule ^. #format]-           ]--    conflictingFormatErrors =-      [ ConflictingFieldFormat (topLevelFieldPath key) profileFormat typeFormat-      | rule <- rawSpec ^. #types,-        let typeRules = compileRules (rule ^. #frontmatter),-        (key, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),-        Just profileFormat <- [profileRule ^. #format],-        Just typeFormat <- [typeRule ^. #format],-        mergeFieldFormat (Just profileFormat) (Just typeFormat) == Nothing-      ]-        <> [ ConflictingFieldFormat (nestedDefinitionPath parentKey nestedKey) profileFormat typeFormat-           | rule <- rawSpec ^. #types,-             let typeRules = compileRules (rule ^. #frontmatter),-             (parentKey, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),-             Just profileNested <- [profileRule ^. #elementFields],-             Just typeNested <- [typeRule ^. #elementFields],-             (nestedKey, (profileNestedRule, typeNestedRule)) <- Map.toAscList (Map.intersectionWith (,) profileNested typeNested),-             Just profileFormat <- [profileNestedRule ^. #format],-             Just typeFormat <- [typeNestedRule ^. #format],-             mergeFieldFormat (Just profileFormat) (Just typeFormat) == Nothing-           ]--    conditionDefinitionErrors =-      conditionErrors Nothing Nothing (rawSpec ^. #frontmatter) baseRules-        <> concat-          [ let typeRules = compileRules (rule ^. #frontmatter)-                mergedRules = mergeRules baseRules typeRules-             in conditionErrors (Just (rule ^. #type_)) Nothing (rule ^. #frontmatter) mergedRules-          | rule <- rawSpec ^. #types-          ]--    conditionErrors scope parent rules effectiveRules =-      concatMap (fieldConditionErrors scope parent effectiveRules) (rules ^. #required <> rules ^. #recommended)-        <> [ deadCondition scope parent (rawRule ^. #field)-           | rawRule <- rules ^. #optional,-             isJust (rawRule ^. #when)-           ]-        <> concat-          [ case (rawRule ^. #elementFields, Map.lookup (rawRule ^. #field) effectiveRules >>= (^. #elementFields)) of-              (Just nestedRules, Just effectiveNestedRules) ->-                concatMap-                  (fieldConditionErrors scope (Just (rawRule ^. #field)) effectiveNestedRules)-                  (nestedRules ^. #required <> nestedRules ^. #recommended)-                  <> [ deadCondition scope (Just (rawRule ^. #field)) (nestedRule ^. #field)-                     | nestedRule <- nestedRules ^. #optional,-                       isJust (nestedRule ^. #when)-                     ]-              _ -> []-          | rawRule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional-          ]--    -- A condition gates presence, and an optional rule has no presence clause to-    -- gate, so the pairing is dead in the descriptor rather than a weaker rule.-    deadCondition scope parent key =-      OptionalFieldWithCondition-        scope-        (maybe (topLevelFieldPath key) (\parentKey -> nestedDefinitionPath parentKey key) parent)--    fieldConditionErrors scope parent effectiveRules rawRule =-      case rawRule ^. #when of-        Nothing -> []-        Just FieldCondition {field = sourceKey, hasValue = conditionValues} ->-          let targetKey = rawRule ^. #field-              targetPath = maybe (topLevelFieldPath targetKey) (\parentKey -> nestedDefinitionPath parentKey targetKey) parent-              sourcePath = maybe (topLevelFieldPath sourceKey) (\parentKey -> nestedDefinitionPath parentKey sourceKey) parent-              normalizedValues = deduplicate conditionValues-              sourceErrors =-                case Map.lookup sourceKey effectiveRules of-                  Nothing -> [ConditionFieldNotDeclared scope targetPath sourcePath]-                  Just sourceRule ->-                    [ ConditionFieldNotScalar scope targetPath sourcePath (sourceRule ^. #cardinality)-                    | sourceRule ^. #cardinality /= Scalar-                    ]-                      <> [ ConditionFieldOpenVocabulary scope targetPath sourcePath-                         | null (sourceRule ^. #allowedValues)-                         ]-                      <> let unreachable = filter (`notElem` sourceRule ^. #allowedValues) normalizedValues-                          in [ ConditionFieldHasUnreachableValues scope targetPath sourcePath unreachable (sourceRule ^. #allowedValues)-                             | not (null (sourceRule ^. #allowedValues)),-                               not (null unreachable)-                             ]-           in [EmptyConditionValues scope targetPath sourcePath | null normalizedValues]-                <> [SelfConditionalField scope targetPath | targetKey == sourceKey]-                <> sourceErrors--    referenceDefinitionErrors =-      List.nub $-        concatMap rawReferenceErrors scopedRules-          <> concatMap mergedReferenceErrors (rawSpec ^. #types)-      where-        declaredPrefixes = mapMaybe (^. #idPrefix) (rawSpec ^. #types)-        scopedRules =-          (Nothing, rawSpec ^. #frontmatter)-            : [(Just (rule ^. #type_), rule ^. #frontmatter) | rule <- rawSpec ^. #types]--        rawReferenceErrors (scope, rules) =-          concatMap (fieldReferenceErrors scope) (rules ^. #required <> rules ^. #recommended <> rules ^. #optional)--        fieldReferenceErrors scope rule =-          case rule ^. #reference of-            Nothing -> []-            Just policy ->-              let path = topLevelFieldPath (rule ^. #field)-                  prefix = policy ^. #localPrefix-                  schemes = deduplicateSchemes (policy ^. #externalUriSchemes)-               in [InvalidReferencePrefix scope path prefix | not (validDocumentHandlePrefix prefix)]-                    <> [ReferencePrefixNotDeclared scope path prefix | prefix `notElem` declaredPrefixes]-                    <> [ReferenceRequiresIdField scope path | isNothing (rawSpec ^. #idField)]-                    <> [InvalidExternalReferenceScheme scope path scheme | scheme <- schemes, not (validUriScheme scheme)]-                    <> [ReferenceWithFormat scope path fieldFormat | Just fieldFormat <- [rule ^. #format]]--        mergedReferenceErrors typeRule =-          [ ConflictingReferencePrefix (typeRule ^. #type_) (topLevelFieldPath key) (profilePolicy ^. #localPrefix) (typePolicy ^. #localPrefix)-          | let typeFields = compileRules (typeRule ^. #frontmatter),-            (key, (profileRule, typeFieldRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeFields),-            Just profilePolicy <- [profileRule ^. #reference],-            Just typePolicy <- [typeFieldRule ^. #reference],-            profilePolicy ^. #localPrefix /= typePolicy ^. #localPrefix-          ]-            <> [ ReferenceWithFormat (Just (typeRule ^. #type_)) (topLevelFieldPath key) fieldFormat-               | let typeFields = compileRules (typeRule ^. #frontmatter),-                 (key, (profileRule, typeFieldRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeFields),-                 (referenceRule, formatRule) <- [(profileRule, typeFieldRule), (typeFieldRule, profileRule)],-                 isJust (referenceRule ^. #reference),-                 Just fieldFormat <- [formatRule ^. #format]-               ]--    renderFieldPathKey (FieldPath (firstSegment :| remainingSegments)) =-      Text.intercalate "." (map renderSegment (firstSegment : remainingSegments))-    renderSegment (FieldName name) = name-    renderSegment (ArrayIndex elementIndex) = Text.pack (show elementIndex)--compileRules :: FrontmatterRules -> Map Text EffectiveFieldRule-compileRules FrontmatterRules {required, recommended, optional} =-  Map.fromList-    ( [ (rule ^. #field, compileFieldRule RequiredField rule)-      | rule <- required-      ]-        <> [ (rule ^. #field, compileFieldRule RecommendedField rule)-           | rule <- recommended-           ]-        <> [ (rule ^. #field, compileOptionalFieldRule rule)-           | rule <- optional-           ]-    )---- | Compile a rule the profile documents but never demands. It carries no--- presence clause, so 'applicablePresenceClause' can never find one to report in--- either validation mode, while every value check still runs from the--- present-value branch. This is also the value constraints a required or--- recommended rule is built from.-compileOptionalFieldRule :: FieldRule -> EffectiveFieldRule-compileOptionalFieldRule rule =-  EffectiveFieldRule-    { presenceClauses = [],-      description = rule ^. #description,-      allowedValues = deduplicate (rule ^. #allowedValues),-      cardinality =-        case (rule ^. #elementFields, rule ^. #cardinality) of-          (Just _, Any) -> List-          (_, cardinality) -> cardinality,-      format = rule ^. #format,-      elementFields = compileNestedRules <$> rule ^. #elementFields,-      reference = compileReferenceRule <$> rule ^. #reference-    }--compileFieldRule :: FieldRequirement -> FieldRule -> EffectiveFieldRule-compileFieldRule requirement rule =-  (compileOptionalFieldRule rule)-    { presenceClauses = [PresenceClause requirement (compileCondition <$> rule ^. #when)]-    }--compileNestedRules :: NestedRules -> Map Text EffectiveFieldRule-compileNestedRules NestedRules {required, recommended, optional} =-  Map.fromList-    ( [ (rule ^. #field, compileNestedFieldRule RequiredField rule)-      | rule <- required-      ]-        <> [ (rule ^. #field, compileNestedFieldRule RecommendedField rule)-           | rule <- recommended-           ]-        <> [ (rule ^. #field, compileOptionalNestedFieldRule rule)-           | rule <- optional-           ]-    )---- | The nested counterpart of 'compileOptionalFieldRule'.-compileOptionalNestedFieldRule :: NestedFieldRule -> EffectiveFieldRule-compileOptionalNestedFieldRule rule =-  EffectiveFieldRule-    { presenceClauses = [],-      description = rule ^. #description,-      allowedValues = deduplicate (rule ^. #allowedValues),-      cardinality = rule ^. #cardinality,-      format = rule ^. #format,-      elementFields = Nothing,-      reference = Nothing-    }--compileNestedFieldRule :: FieldRequirement -> NestedFieldRule -> EffectiveFieldRule-compileNestedFieldRule requirement rule =-  (compileOptionalNestedFieldRule rule)-    { presenceClauses = [PresenceClause requirement (compileCondition <$> rule ^. #when)]-    }--mergeRules :: Map Text EffectiveFieldRule -> Map Text EffectiveFieldRule -> Map Text EffectiveFieldRule-mergeRules = Map.unionWith mergeEffectiveFieldRule--mergeEffectiveFieldRule :: EffectiveFieldRule -> EffectiveFieldRule -> EffectiveFieldRule-mergeEffectiveFieldRule profileRule typeRule =-  EffectiveFieldRule-    { presenceClauses = profileRule ^. #presenceClauses <> typeRule ^. #presenceClauses,-      description = typeRule ^. #description <|> profileRule ^. #description,-      allowedValues = mergeVocabulary (profileRule ^. #allowedValues) (typeRule ^. #allowedValues),-      cardinality = mergeCardinality (profileRule ^. #cardinality) (typeRule ^. #cardinality),-      format = fromMaybe (profileRule ^. #format) (mergeFieldFormat (profileRule ^. #format) (typeRule ^. #format)),-      elementFields = mergeElementFields (profileRule ^. #elementFields) (typeRule ^. #elementFields),-      reference = fromMaybe (profileRule ^. #reference) (mergeReferenceRule (profileRule ^. #reference) (typeRule ^. #reference))-    }--compileCondition :: FieldCondition -> CompiledCondition-compileCondition rawCondition =-  CompiledCondition-    { field = rawCondition ^. #field,-      hasValue = deduplicate (rawCondition ^. #hasValue)-    }--compileReferenceRule :: HandleReferenceRule -> HandleReferenceRule-compileReferenceRule policy =-  HandleReferenceRule-    { localPrefix = policy ^. #localPrefix,-      externalUriSchemes = map Text.toCaseFold (deduplicateSchemes (policy ^. #externalUriSchemes)),-      allowSelf = policy ^. #allowSelf-    }--mergeElementFields :: Maybe (Map Text EffectiveFieldRule) -> Maybe (Map Text EffectiveFieldRule) -> Maybe (Map Text EffectiveFieldRule)-mergeElementFields Nothing typeRules = typeRules-mergeElementFields profileRules Nothing = profileRules-mergeElementFields (Just profileRules) (Just typeRules) = Just (Map.unionWith mergeEffectiveFieldRule profileRules typeRules)--mergeReferenceRule :: Maybe HandleReferenceRule -> Maybe HandleReferenceRule -> Maybe (Maybe HandleReferenceRule)-mergeReferenceRule Nothing typePolicy = Just typePolicy-mergeReferenceRule profilePolicy Nothing = Just profilePolicy-mergeReferenceRule (Just profilePolicy) (Just typePolicy)-  | profilePolicy ^. #localPrefix == typePolicy ^. #localPrefix =-      Just . Just $-        HandleReferenceRule-          { localPrefix = profilePolicy ^. #localPrefix,-            externalUriSchemes =-              filter-                (`Set.member` Set.fromList (typePolicy ^. #externalUriSchemes))-                (profilePolicy ^. #externalUriSchemes),-            allowSelf = profilePolicy ^. #allowSelf && typePolicy ^. #allowSelf-          }-  | otherwise = Nothing--mergeFieldFormat :: Maybe FieldFormat -> Maybe FieldFormat -> Maybe (Maybe FieldFormat)-mergeFieldFormat Nothing typeFormat = Just typeFormat-mergeFieldFormat profileFormat Nothing = Just profileFormat-mergeFieldFormat (Just Uri) (Just typeFormat@(UriWithScheme _)) = Just (Just typeFormat)-mergeFieldFormat (Just profileFormat@(UriWithScheme _)) (Just Uri) = Just (Just profileFormat)-mergeFieldFormat profileFormat typeFormat-  | profileFormat == typeFormat = Just profileFormat-  | otherwise = Nothing--invalidFormatParameter :: FieldFormat -> Maybe (FieldFormat, Text)-invalidFormatParameter fieldFormat =-  case fieldFormat of-    UriWithScheme scheme-      | not (validUriScheme scheme) -> Just (fieldFormat, scheme)-    DocumentHandle prefix-      | not (validDocumentHandlePrefix prefix) -> Just (fieldFormat, prefix)-    _ -> Nothing--validUriScheme :: Text -> Bool-validUriScheme scheme =-  case Text.uncons scheme of-    Just (firstCharacter, rest) -> isAsciiLetter firstCharacter && Text.all validRest rest-    Nothing -> False-  where-    validRest character =-      isAsciiLetter character-        || ('0' <= character && character <= '9')-        || character `elem` ['+', '.', '-']--validDocumentHandlePrefix :: Text -> Bool-validDocumentHandlePrefix prefix =-  case parseDocumentId (prefix <> "-1") of-    Just documentId -> documentId ^. #prefix == prefix-    Nothing -> False--isAsciiLetter :: Char -> Bool-isAsciiLetter character = isAsciiLower character || isAsciiUpper character--mergeCardinality :: Cardinality -> Cardinality -> Cardinality-mergeCardinality Any typeCardinality = typeCardinality-mergeCardinality profileCardinality Any = profileCardinality-mergeCardinality profileCardinality _typeCardinality = profileCardinality--mergeVocabulary :: [Text] -> [Text] -> [Text]-mergeVocabulary [] typeValues = typeValues-mergeVocabulary profileValues [] = profileValues-mergeVocabulary profileValues typeValues =-  filter (`Set.member` Set.fromList typeValues) profileValues--deduplicate :: [Text] -> [Text]-deduplicate = go Set.empty-  where-    go _ [] = []-    go seen (value : rest)-      | value `Set.member` seen = go seen rest-      | otherwise = value : go (Set.insert value seen) rest--deduplicateSchemes :: [Text] -> [Text]-deduplicateSchemes = go Set.empty-  where-    go _ [] = []-    go seen (scheme : rest)-      | normalized `Set.member` seen = go seen rest-      | otherwise = scheme : go (Set.insert normalized seen) rest-      where-        normalized = Text.toCaseFold scheme--effectiveRulesForType :: CompiledProfile -> Text -> Map Text EffectiveFieldRule-effectiveRulesForType compiled ctype =-  Map.findWithDefault (compiled ^. #baseRules) ctype (compiled ^. #rulesByType)--profileFieldDescriptionForType :: CompiledProfile -> Text -> Text -> Maybe Text-profileFieldDescriptionForType compiled ctype key =-  Map.lookup key (effectiveRulesForType compiled ctype) >>= (^. #description)---- | A parsed document handle: an ASCII-letter-led alphanumeric prefix and a--- positive number, rendered as @PREFIX-N@.-data DocumentId = DocumentId-  { prefix :: !Text,-    number :: !Natural-  }-  deriving stock (Generic, Eq, Ord, Show)---- | Parse a strict document handle. The prefix contains one or more ASCII--- letters or digits and begins with a letter. It is followed by exactly one--- hyphen and a positive decimal number with no leading zero. Thus @ADR-7@--- parses, while @ADR-007@, @ADR-0@, @ADR-@, @-7@, @adr 7@, and--- @ADR-7-extra@ do not.-parseDocumentId :: Text -> Maybe DocumentId-parseDocumentId raw =-  case Text.splitOn "-" raw of-    [prefixText, numberText]-      | validPrefix prefixText,-        validNumberText numberText ->-          case Text.Read.decimal numberText of-            Right (parsedNumber, remainder)-              | Text.null remainder,-                parsedNumber > 0 ->-                  Just (DocumentId prefixText parsedNumber)-            _ -> Nothing-    _ -> Nothing-  where-    validPrefix value =-      case Text.uncons value of-        Just (firstCharacter, rest) ->-          isAsciiLetter firstCharacter && Text.all isAsciiAlphaNumeric rest-        Nothing -> False-    validNumberText value =-      case Text.uncons value of-        Just (firstCharacter, rest) ->-          firstCharacter >= '1'-            && firstCharacter <= '9'-            && Text.all isAsciiDigit rest-        Nothing -> False-    isAsciiDigit character =-      character >= '0' && character <= '9'-    isAsciiAlphaNumeric character =-      isAsciiLetter character || isAsciiDigit character---- | Render a document handle as @PREFIX-N@.-renderDocumentId :: DocumentId -> Text-renderDocumentId DocumentId {prefix, number} =-  prefix <> "-" <> Text.pack (show number)---- | Every well-formed handle under the profile's ID field, paired with the--- concept carrying it and sorted by prefix, number, then concept ID. Concepts--- without a well-formed handle are omitted. A profile with no ID field yields--- an empty list.-documentIdsInBundle :: ProfileSpec -> [Concept] -> [(DocumentId, ConceptId)]-documentIdsInBundle spec concepts =-  case spec ^. #idField of-    Nothing -> []-    Just fieldName ->-      List.sortOn-        (\(documentId, cid) -> (documentId, renderConceptId cid))-        [ (documentId, conceptIdOf concept)-        | concept <- concepts,-          Just (String rawDocumentId) <- [frontmatterLookup fieldName (conceptFrontmatter concept)],-          Just documentId <- [parseDocumentId rawDocumentId]-        ]---- | Allocate one more than the highest document-ID number already used for the--- given prefix, or number 1 when the prefix is unused. Gaps are deliberately--- not filled: reusing a retired number could make an old reference silently--- point at a different document.-nextDocumentId :: ProfileSpec -> [Concept] -> Text -> DocumentId-nextDocumentId spec concepts requestedPrefix =-  DocumentId-    { prefix = requestedPrefix,-      number = highestNumber + 1-    }-  where-    highestNumber =-      List.foldl'-        max-        0-        [ documentId ^. #number-        | (documentId, _) <- documentIdsInBundle spec concepts,-          documentId ^. #prefix == requestedPrefix-        ]---- | One structural segment of a frontmatter path. EP-2 produces top-level--- 'FieldName' paths; later bounded nested validation can append field names and--- array indexes without encoding paths as ad hoc text.-data FieldPathSegment-  = FieldName Text-  | ArrayIndex Int-  deriving stock (Generic, Eq, Ord, Show)--newtype FieldPath = FieldPath-  { segments :: NonEmpty FieldPathSegment-  }-  deriving stock (Generic, Eq, Ord, Show)--topLevelFieldPath :: Text -> FieldPath-topLevelFieldPath key = FieldPath (FieldName key :| [])--nestedDefinitionPath :: Text -> Text -> FieldPath-nestedDefinitionPath parent child =-  FieldPath (FieldName parent :| [FieldName child])--nestedValuePath :: Text -> Int -> Text -> FieldPath-nestedValuePath parent elementIndex child =-  FieldPath (FieldName parent :| [ArrayIndex elementIndex, FieldName child])--nestedElementPath :: Text -> Int -> FieldPath-nestedElementPath parent elementIndex =-  FieldPath (FieldName parent :| [ArrayIndex elementIndex])---- | A single deviation from a profile. Advisory by default at the CLI layer.-data ProfileViolation-  = -- | concept's @type@ is not listed in the profile and unknown types are disallowed-    TypeNotInProfile ConceptId Text-  | -- | a required frontmatter key is missing or empty (concept, key, activating condition)-    MissingProfileField ConceptId Text (Maybe FieldCondition)-  | -- | a recommended frontmatter key is missing under strict authoring-    MissingRecommendedProfileField ConceptId Text (Maybe FieldCondition)-  | -- | a required field is missing inside one list element record-    MissingNestedProfileField ConceptId FieldPath (Maybe FieldCondition)-  | -- | a recommended nested field is missing under strict authoring-    MissingRecommendedNestedProfileField ConceptId FieldPath (Maybe FieldCondition)-  | -- | a present value is outside the effective textual vocabulary-    ValueNotInVocabulary ConceptId FieldPath [Text] Value-  | -- | a present value has the wrong scalar/list shape-    CardinalityMismatch ConceptId FieldPath Cardinality Value-  | -- | a present value does not satisfy its named textual format-    ValueFormatMismatch ConceptId FieldPath FieldFormat Value-  | -- | a local reference has the right prefix but no valid owner in this bundle-    DanglingHandleReference ConceptId FieldPath Text-  | -- | a parsed local handle uses a prefix other than the declared target prefix-    ReferenceHandlePrefixMismatch ConceptId FieldPath Text Text-  | -- | a reference value is neither textual local handle nor valid absolute URI-    MalformedDocumentReference ConceptId FieldPath Value-  | -- | an absolute external URI uses a scheme the profile did not permit-    ExternalReferenceSchemeNotAllowed ConceptId FieldPath Text [Text]-  | -- | a local handle resolves to the concept carrying the reference-    SelfDocumentReference ConceptId FieldPath Text-  | -- | a closed profile does not declare this top-level field-    FieldNotInProfile ConceptId Text-  | -- | a declared list element is not an object record-    NestedElementNotRecord ConceptId FieldPath Value-  | -- | concept's file path does not match the type rule's pattern (concept, type, pattern)-    PathPatternMismatch ConceptId Text Text-  | -- | type rule requires a resource scheme but resource is absent (concept, type, scheme)-    MissingResource ConceptId Text Text-  | -- | resource present but its scheme is wrong (concept, expected scheme, actual resource)-    ResourceSchemeMismatch ConceptId Text Text-  | -- | required @# Schema@ section is absent (concept, type)-    MissingSchemaSection ConceptId Text-  | -- | @# Schema@ table columns do not match (concept, type, expected, actual)-    SchemaColumnsMismatch ConceptId Text [Text] [Text]-  | -- | type rule declares an @idPrefix@ but the concept has no handle (concept, type, prefix)-    MissingDocumentId ConceptId Text Text-  | -- | handle present but malformed for the declared prefix (concept, prefix, actual value)-    MalformedDocumentId ConceptId Text Text-  | -- | the same handle appears on more than one concept (handle, concept, other concept)-    DuplicateDocumentId Text ConceptId ConceptId-  deriving stock (Generic, Eq, Show)---- | Check every concept against a compiled profile, returning all deviations.--- Profile-wide rules apply even to unknown types; a matching type rule adds its--- frontmatter rules and the existing type-specific structural checks.-validateProfile :: ValidationProfile -> CompiledProfile -> [Concept] -> [ProfileViolation]-validateProfile validationProfile compiled concepts =-  concatMap checkConcept sortedConcepts <> checkDuplicateDocumentIds spec sortedConcepts-  where-    spec = compiledProfileSpec compiled-    sortedConcepts = List.sortOn (renderConceptId . conceptIdOf) concepts-    rulesByType = [(rule ^. #type_, rule) | rule <- spec ^. #types]-    validDocumentIdIndex = buildValidDocumentIdIndex spec rulesByType sortedConcepts--    checkConcept concept =-      let cid = conceptIdOf concept-          ctype = conceptType concept-          fieldViolations = checkFields cid ctype concept <> checkUnknownFields cid ctype concept-       in case lookup ctype rulesByType of-            Nothing ->-              [TypeNotInProfile cid ctype | not (spec ^. #allowUnknownTypes)] <> fieldViolations-            Just rule ->-              fieldViolations-                <> checkPath cid ctype rule-                <> checkResource cid ctype rule concept-                <> checkSchema cid ctype rule concept-                <> checkDocumentId spec cid ctype rule concept--    checkFields cid ctype concept =-      concatMap checkField (Map.toAscList (effectiveRulesForType compiled ctype))-      where-        checkField (key, rule) =-          case evaluateFieldValue (rule ^. #cardinality) (frontmatterLookup key (conceptFrontmatter concept)) of-            FieldAbsent actual ->-              presenceViolations key rule-                <> maybe [] (vocabularyViolations key rule) actual-                <> maybe [] (formatViolations key rule) actual-                <> maybe [] (referenceViolations key rule) actual-            FieldPresent actual ->-              vocabularyViolations key rule actual-                <> formatViolations key rule actual-                <> referenceViolations key rule actual-                <> nestedViolations key rule actual-            FieldWrongShape actual -> [CardinalityMismatch cid (topLevelFieldPath key) (rule ^. #cardinality) actual]--        presenceViolations key rule =-          case applicablePresenceClause validationProfile (\sourceKey -> frontmatterLookup sourceKey (conceptFrontmatter concept)) rule of-            Nothing -> []-            Just clause ->-              [ case clause ^. #requirement of-                  RequiredField -> MissingProfileField cid key (conditionForViolation <$> clause ^. #condition)-                  RecommendedField -> MissingRecommendedProfileField cid key (conditionForViolation <$> clause ^. #condition)-              ]-        vocabularyViolations key rule actual =-          [ ValueNotInVocabulary cid (topLevelFieldPath key) (rule ^. #allowedValues) actual-          | not (null (rule ^. #allowedValues)),-            not (valueMatchesVocabulary (rule ^. #allowedValues) actual)-          ]-        formatViolations key rule actual =-          [ ValueFormatMismatch cid (topLevelFieldPath key) fieldFormat actual-          | Just fieldFormat <- [rule ^. #format],-            not (valueMatchesFormat fieldFormat actual)-          ]-        referenceViolations key rule actual =-          case rule ^. #reference of-            Nothing -> []-            Just policy -> validateReferenceValue validDocumentIdIndex cid (topLevelFieldPath key) policy actual--        nestedViolations parentKey parentRule = \case-          Array elementValues-            | Just nestedRules <- parentRule ^. #elementFields ->-                concat-                  [ case elementValue of-                      Object objectFields ->-                        concatMap-                          (checkNestedField parentKey elementIndex objectFields)-                          (Map.toAscList nestedRules)-                      _ -> [NestedElementNotRecord cid (nestedElementPath parentKey elementIndex) elementValue]-                  | (elementIndex, elementValue) <- zip [0 ..] (Vector.toList elementValues)-                  ]-          _ -> []--        checkNestedField parentKey elementIndex objectFields (key, rule) =-          let path = nestedValuePath parentKey elementIndex key-              actualValue = Aeson.KeyMap.lookup (Aeson.Key.fromText key) objectFields-           in case evaluateFieldValue (rule ^. #cardinality) actualValue of-                FieldAbsent actual ->-                  nestedPresenceViolations objectFields path rule-                    <> maybe [] (nestedVocabularyViolations path rule) actual-                    <> maybe [] (nestedFormatViolations path rule) actual-                FieldPresent actual ->-                  nestedVocabularyViolations path rule actual-                    <> nestedFormatViolations path rule actual-                FieldWrongShape actual -> [CardinalityMismatch cid path (rule ^. #cardinality) actual]--        nestedPresenceViolations objectFields path rule =-          case applicablePresenceClause validationProfile lookupSibling rule of-            Nothing -> []-            Just clause ->-              [ case clause ^. #requirement of-                  RequiredField -> MissingNestedProfileField cid path (conditionForViolation <$> clause ^. #condition)-                  RecommendedField -> MissingRecommendedNestedProfileField cid path (conditionForViolation <$> clause ^. #condition)-              ]-          where-            lookupSibling sourceKey = Aeson.KeyMap.lookup (Aeson.Key.fromText sourceKey) objectFields-        nestedVocabularyViolations path rule actual =-          [ ValueNotInVocabulary cid path (rule ^. #allowedValues) actual-          | not (null (rule ^. #allowedValues)),-            not (valueMatchesVocabulary (rule ^. #allowedValues) actual)-          ]-        nestedFormatViolations path rule actual =-          [ ValueFormatMismatch cid path fieldFormat actual-          | Just fieldFormat <- [rule ^. #format],-            not (valueMatchesFormat fieldFormat actual)-          ]--    checkUnknownFields cid ctype concept-      | spec ^. #allowUnknownFields = []-      | otherwise =-          [ FieldNotInProfile cid key-          | key <- frontmatterKeys (conceptFrontmatter concept),-            key `Set.notMember` allowedFields ctype-          ]--    allowedFields ctype =-      coreFrontmatterFields-        <> Map.keysSet (effectiveRulesForType compiled ctype)-        <> maybe Set.empty Set.singleton (spec ^. #idField)---- | Index only handles that are valid owners under the compiled profile's raw--- type declarations: the concept has a matching type rule, that rule declares--- the parsed handle's exact prefix, and the profile declares the owning field.--- Multiple owners are retained so a duplicate target still counts as existing;--- the existing bundle-wide duplicate diagnostic remains authoritative.-buildValidDocumentIdIndex :: ProfileSpec -> [(Text, TypeRule)] -> [Concept] -> Map DocumentId [ConceptId]-buildValidDocumentIdIndex spec rulesByType concepts =-  case spec ^. #idField of-    Nothing -> Map.empty-    Just fieldName ->-      Map.fromListWith-        (flip (<>))-        [ (documentId, [conceptIdOf concept])-        | concept <- concepts,-          Just typeRule <- [lookup (conceptType concept) rulesByType],-          Just expectedPrefix <- [typeRule ^. #idPrefix],-          Just (String rawDocumentId) <- [frontmatterLookup fieldName (conceptFrontmatter concept)],-          Just documentId <- [parseDocumentId rawDocumentId],-          documentId ^. #prefix == expectedPrefix-        ]--validateReferenceValue :: Map DocumentId [ConceptId] -> ConceptId -> FieldPath -> HandleReferenceRule -> Value -> [ProfileViolation]-validateReferenceValue validOwners sourceConcept path policy = \case-  String rawReference -> validateReferenceText validOwners sourceConcept path policy rawReference-  Array values ->-    concat-      [ case value of-          String rawReference -> validateReferenceText validOwners sourceConcept (appendArrayIndex path elementIndex) policy rawReference-          _ -> [MalformedDocumentReference sourceConcept (appendArrayIndex path elementIndex) value]-      | (elementIndex, value) <- zip [0 ..] (Vector.toList values)-      ]-  actual -> [MalformedDocumentReference sourceConcept path actual]--validateReferenceText :: Map DocumentId [ConceptId] -> ConceptId -> FieldPath -> HandleReferenceRule -> Text -> [ProfileViolation]-validateReferenceText validOwners sourceConcept path policy rawReference =-  case parseDocumentId rawReference of-    Just documentId-      | documentId ^. #prefix /= policy ^. #localPrefix ->-          [ReferenceHandlePrefixMismatch sourceConcept path rawReference (policy ^. #localPrefix)]-      | otherwise ->-          case Map.lookup documentId validOwners of-            Nothing -> [DanglingHandleReference sourceConcept path rawReference]-            Just owners-              | not (policy ^. #allowSelf),-                sourceConcept `elem` owners ->-                  [SelfDocumentReference sourceConcept path rawReference]-              | otherwise -> []-    Nothing ->-      case parseURI (Text.unpack rawReference) of-        Just parsed-          | not (Text.null normalizedScheme), normalizedScheme `elem` policy ^. #externalUriSchemes -> []-          | not (Text.null normalizedScheme) ->-              [ ExternalReferenceSchemeNotAllowed-                  sourceConcept-                  path-                  normalizedScheme-                  (policy ^. #externalUriSchemes)-              ]-          | otherwise -> [MalformedDocumentReference sourceConcept path (String rawReference)]-          where-            normalizedScheme = Text.toCaseFold (Text.dropWhileEnd (== ':') (Text.pack (uriScheme parsed)))-        Nothing -> [MalformedDocumentReference sourceConcept path (String rawReference)]--appendArrayIndex :: FieldPath -> Int -> FieldPath-appendArrayIndex (FieldPath pathSegments) elementIndex =-  FieldPath (pathSegments <> (ArrayIndex elementIndex :| []))--applicablePresenceClause :: ValidationProfile -> (Text -> Maybe Value) -> EffectiveFieldRule -> Maybe PresenceClause-applicablePresenceClause validationProfile lookupValue rule =-  List.find applies requiredClauses-    <|> if validationProfile == StrictAuthoring then List.find applies recommendedClauses else Nothing-  where-    requiredClauses = filter ((== RequiredField) . (^. #requirement)) (rule ^. #presenceClauses)-    recommendedClauses = filter ((== RecommendedField) . (^. #requirement)) (rule ^. #presenceClauses)-    applies clause = maybe True conditionApplies (clause ^. #condition)-    conditionApplies condition =-      case lookupValue (condition ^. #field) of-        Just (String actual) -> actual `elem` condition ^. #hasValue-        _ -> False--conditionForViolation :: CompiledCondition -> FieldCondition-conditionForViolation condition =-  FieldCondition-    { field = condition ^. #field,-      hasValue = condition ^. #hasValue-    }--valueMatchesVocabulary :: [Text] -> Value -> Bool-valueMatchesVocabulary allowed = \case-  String value -> value `elem` allowed-  Array values -> all elementMatches (Vector.toList values)-  _ -> False-  where-    elementMatches (String value) = value `elem` allowed-    elementMatches _ = False--valueMatchesFormat :: FieldFormat -> Value -> Bool-valueMatchesFormat fieldFormat = \case-  String value -> textMatchesFormat fieldFormat value-  Array values -> all elementMatches (Vector.toList values)-  _ -> False-  where-    elementMatches (String value) = textMatchesFormat fieldFormat value-    elementMatches _ = False--textMatchesFormat :: FieldFormat -> Text -> Bool-textMatchesFormat fieldFormat value =-  case fieldFormat of-    Rfc3339Utc ->-      hasExtendedUtcShape value-        && isJust (iso8601ParseM (Text.unpack value) :: Maybe UTCTime)-    Date ->-      hasExtendedDateShape value-        && isJust (iso8601ParseM (Text.unpack value) :: Maybe Day)-    Uri -> isJust (parseURI (Text.unpack value))-    UriWithScheme expectedScheme ->-      case parseURI (Text.unpack value) of-        Just parsed ->-          Text.toCaseFold (Text.dropWhileEnd (== ':') (Text.pack (uriScheme parsed)))-            == Text.toCaseFold expectedScheme-        Nothing -> False-    DocumentHandle expectedPrefix ->-      case parseDocumentId value of-        Just documentId -> documentId ^. #prefix == expectedPrefix-        Nothing -> False--hasExtendedDateShape :: Text -> Bool-hasExtendedDateShape value =-  Text.length value == 10-    && Text.index value 4 == '-'-    && Text.index value 7 == '-'--hasExtendedUtcShape :: Text -> Bool-hasExtendedUtcShape value =-  Text.length value >= 20-    && Text.index value 4 == '-'-    && Text.index value 7 == '-'-    && Text.index value 10 == 'T'-    && Text.index value 13 == ':'-    && Text.index value 16 == ':'-    && Text.last value == 'Z'--data FieldValueEvaluation-  = FieldAbsent (Maybe Value)-  | FieldPresent Value-  | FieldWrongShape Value--evaluateFieldValue :: Cardinality -> Maybe Value -> FieldValueEvaluation-evaluateFieldValue _ Nothing = FieldAbsent Nothing-evaluateFieldValue Any (Just actual)-  | legacyValueIsPresent actual = FieldPresent actual-  | otherwise = FieldAbsent (Just actual)-evaluateFieldValue Scalar (Just actual) =-  case actual of-    String value-      | Text.null (Text.strip value) -> FieldAbsent (Just actual)-      | otherwise -> FieldPresent actual-    Number _ -> FieldPresent actual-    Bool _ -> FieldPresent actual-    _ -> FieldWrongShape actual-evaluateFieldValue List (Just actual) =-  case actual of-    Array values-      | null values -> FieldAbsent (Just actual)-      | otherwise -> FieldPresent actual-    _ -> FieldWrongShape actual--legacyValueIsPresent :: Value -> Bool-legacyValueIsPresent = \case-  String value -> not (Text.null (Text.strip value))-  Array values -> not (null values)-  _ -> False---- | Check a profile-declared document ID for one concept.-checkDocumentId :: ProfileSpec -> ConceptId -> Text -> TypeRule -> Concept -> [ProfileViolation]-checkDocumentId spec cid ctype rule concept =-  case (spec ^. #idField, rule ^. #idPrefix) of-    (Just fieldName, Just expectedPrefix) ->-      case frontmatterLookup fieldName (conceptFrontmatter concept) of-        Just (String value)-          | not (Text.null (Text.strip value)) ->-              case parseDocumentId value of-                Just documentId-                  | documentId ^. #prefix == expectedPrefix -> []-                _ -> [MalformedDocumentId cid expectedPrefix value]-        _ -> [MissingDocumentId cid ctype expectedPrefix]-    _ -> []---- | Check every non-empty value under the profile's ID field for bundle-wide--- uniqueness. Concept IDs are sorted before grouping so output is deterministic.-checkDuplicateDocumentIds :: ProfileSpec -> [Concept] -> [ProfileViolation]-checkDuplicateDocumentIds spec concepts =-  case spec ^. #idField of-    Nothing -> []-    Just fieldName ->-      concatMap duplicateViolations (groupedHandles fieldName)-  where-    groupedHandles fieldName =-      List.groupBy-        (\(leftHandle, _) (rightHandle, _) -> leftHandle == rightHandle)-        (handles fieldName)-    handles fieldName =-      List.sortOn-        (\(handle, cid) -> (handle, renderConceptId cid))-        [ (handle, conceptIdOf concept)-        | concept <- concepts,-          Just (String handle) <- [frontmatterLookup fieldName (conceptFrontmatter concept)],-          not (Text.null (Text.strip handle))-        ]-    duplicateViolations ((handle, firstConcept) : duplicates) =-      [ DuplicateDocumentId handle firstConcept duplicateConcept-      | (_, duplicateConcept) <- duplicates-      ]-    duplicateViolations [] = []---- | Project a concept's frontmatter (the document's @frontmatter@ field).-conceptFrontmatter :: Concept -> Frontmatter-conceptFrontmatter concept = conceptDocument concept ^. #frontmatter---- | A type rule's @pathPattern@, when present, constrains where the concept's--- file may live.-checkPath :: ConceptId -> Text -> TypeRule -> [ProfileViolation]-checkPath cid ctype rule =-  case rule ^. #pathPattern of-    Nothing -> []-    Just patternText-      | matchPathPattern patternText cid -> []-      | otherwise -> [PathPatternMismatch cid ctype patternText]---- | Match a concept ID against a segment-glob pattern. @*@ matches exactly one--- segment; a single trailing @**@ matches one or more remaining segments; every--- other segment matches literally. Both segment lists must be consumed exactly,--- except for the trailing @**@ case.-matchPathPattern :: Text -> ConceptId -> Bool-matchPathPattern patternText cid =-  go (Text.splitOn "/" patternText) (Text.splitOn "/" (renderConceptId cid))-  where-    go [] [] = True-    go ["**"] (_ : _) = True-    go ("*" : ps) (_ : ss) = go ps ss-    go (p : ps) (s : ss) = p == s && go ps ss-    go _ _ = False---- | A type rule's @resourceScheme@, when present, requires a @resource:@ value--- whose scheme matches.-checkResource :: ConceptId -> Text -> TypeRule -> Concept -> [ProfileViolation]-checkResource cid ctype rule concept =-  case rule ^. #resourceScheme of-    Nothing -> []-    Just scheme ->-      case conceptResource concept of-        Nothing -> [MissingResource cid ctype scheme]-        Just value-          | (scheme <> "://") `Text.isPrefixOf` value -> []-          | otherwise -> [ResourceSchemeMismatch cid scheme value]---- | A type rule's @# Schema@ contract: when @requireSchemaSection@ is set, the--- body must contain a @# Schema@ section whose table header begins with the--- required @schemaColumns@ (case-insensitive, trimmed, compared as a prefix so a--- team may add trailing columns without tripping the check).-checkSchema :: ConceptId -> Text -> TypeRule -> Concept -> [ProfileViolation]-checkSchema cid ctype rule concept-  | not (rule ^. #requireSchemaSection) = []-  | otherwise =-      case schemaSectionColumns (conceptDocument concept ^. #body) of-        Nothing -> [MissingSchemaSection cid ctype]-        Just actual ->-          let expected = rule ^. #schemaColumns-              norm = map (Text.toLower . Text.strip)-           in [ SchemaColumnsMismatch cid ctype expected actual-              | not (norm expected `List.isPrefixOf` norm actual)-              ]---- | The header-row columns of the first GitHub-flavored table that follows the--- first top-level @# Schema@ heading, or 'Nothing' if there is no Schema heading--- or no following table. Columns are trimmed.-schemaSectionColumns :: Text -> Maybe [Text]-schemaSectionColumns markdown =-  let CMarkGFM.Node _ _ topLevel = CMarkGFM.commonmarkToNode [] [CMarkGFM.extTable] markdown+    PathReferenceRule (..),+    FieldRule (..),+    NestedRules (..),+    NestedFieldRule (..),+    Cardinality (..),+    FieldFormat (..),+    TypeRule (..),+    FieldPath (..),+    FieldPathSegment (..),+    loadProfileFile,+    decodeProfileExpr,+    profileFieldDescription,+    CompiledProfile,+    ProfileDefinitionError (..),+    compileProfile,+    compiledProfileSpec,+    compiledProfileRequiredBundleVersion,+    profileFieldDescriptionForType,++    -- * Compiled rule inspection++    -- | A read-only window onto what a compiled profile actually demands. The+    -- rule types are abstract on purpose: read them through the accessors below+    -- so that later profile features can extend the compiled encoding without+    -- breaking consumers.+    --+    -- Two encodings are easy to misread and are worth stating up front. An+    -- __empty presence-clause list means the key is optional__, not that it is+    -- unconstrained; and an __empty allowed-value list means unconstrained__,+    -- not that no value is permitted.+    EffectiveFieldRule,+    PresenceClause,+    FieldRequirement (..),+    fieldRulePresenceClauses,+    presenceClauseRequirement,+    presenceClauseCondition,+    fieldRuleDescription,+    fieldRuleAllowedValues,+    fieldRuleCardinality,+    fieldRuleFormat,+    fieldRuleReference,+    fieldRulePath,+    fieldRuleElementFields,+    fieldRuleObjectFields,+    compiledProfileTypeNames,+    compiledProfileBaseRules,+    compiledProfileRulesForType,+    renderCardinalityName,+    renderFieldFormatName,++    -- * Validation+    DocumentId (..),+    parseDocumentId,+    renderDocumentId,+    documentIdsInBundle,+    nextDocumentId,+    ProfileViolation (..),+    validateProfile,+    validateProfileWith,+    validateProfileVersion,++    -- * Body inspection+    schemaSectionColumns,+  )+where++import CMarkGFM qualified+import Control.Exception (SomeException, catch)+import Data.Aeson (ToJSON (..), object, (.=))+import Data.Aeson qualified as Aeson+import Data.Aeson.Key qualified as Aeson.Key+import Data.Aeson.KeyMap qualified as Aeson.KeyMap+import Data.Char (isAsciiLower, isAsciiUpper)+import Data.List qualified as List+import Data.Map.Strict (Map)+import Data.Map.Strict qualified as Map+import Data.Maybe (catMaybes, mapMaybe)+import Data.Set (Set)+import Data.Set qualified as Set+import Data.Text qualified as Text+import Data.Text.Read qualified as Text.Read+import Data.Time.Calendar (Day)+import Data.Time.Clock (UTCTime)+import Data.Time.Format.ISO8601 (iso8601ParseM)+import Data.Vector qualified as Vector+import Data.Void (Void)+import Dhall (FromDhall (..), auto, genericAutoWith)+import Dhall qualified+import Dhall.Core (Expr)+import Dhall.Src (Src)+import Network.URI (parseURI, uriScheme)+import Numeric.Natural (Natural)+-- Imported qualified: 'Okf.Actor.HumanActor' is a constructor of 'Actor.Actor'+-- and 'HumanActor' is a constructor of 'FieldFormat', so an unqualified import+-- makes the two ambiguous.+import Okf.Actor qualified as Actor+import Okf.Bundle+  ( BundleInventory,+    Concept,+    bundleInventoryMember,+    bundleInventoryOfConcepts,+    conceptDocument,+    conceptIdOf,+    conceptResource,+    conceptType,+  )+import Okf.ConceptId (ConceptId, conceptIdFromFilePath, renderConceptId)+import Okf.Document+  ( Frontmatter,+    coreFrontmatterFields,+    fieldsSupersededInV02,+    frontmatterKeys,+    frontmatterLookup,+  )+import Okf.Index+  ( OkfVersion (..),+    VersionDeclaration (..),+    parseOkfVersion,+    renderOkfVersion,+    supportedOkfVersion,+  )+import Okf.Markdown (markdownOptions)+import Okf.Path (PathReference (..), classifyPathReference)+-- 'List' and 'Object' are 'Cardinality' constructors here; the names aeson uses+-- for the corresponding 'Value' constructors are reached as 'Aeson.Array' and+-- 'Aeson.Object'.+import Okf.Prelude hiding (List, Object, (.=))+import Okf.Validation (ValidationProfile (..))+import System.FilePath qualified as FilePath+import "generic-lens" Data.Generics.Labels ()++-- | A complete house profile. @description@ is prose documenting the profile as+-- a whole; like every description in this module it is never checked against a+-- bundle and can never produce a 'ProfileViolation'.+--+-- @requireBundleVersion@ and @okfVersion@ are easy to confuse and answer+-- different questions. @okfVersion@ says which version's rules /this profile+-- writes/, and 'compileProfile' checks the profile's own rules against it.+-- @requireBundleVersion@ says what the profile demands of a /bundle/: @Just+-- \"0.2\"@ means the bundle's root @index.md@ must declare @okf_version@ at 0.2+-- or later, checked by 'validateProfileVersion'. Neither constrains the other.+data ProfileSpec = ProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !FrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    requireBundleVersion :: !(Maybe Text),+    types :: ![TypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | Frontmatter keys the profile expects on every concept. @required@ is always+-- checked, @recommended@ only under 'StrictAuthoring', and @optional@ never:+-- an optional key is fully validated whenever it is present and its absence is+-- never a deviation in any mode.+data FrontmatterRules = FrontmatterRules+  { required :: ![FieldRule],+    recommended :: ![FieldRule],+    optional :: ![FieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | A same-scope predicate controlling whether a field's presence rule applies.+-- The source field must compile to a closed scalar textual vocabulary.+data FieldCondition = FieldCondition+  { field :: !Text,+    hasValue :: ![Text]+  }+  deriving stock (Generic, Eq, Ord, Show)+  deriving anyclass (FromDhall)++-- | A top-level field whose textual values point either to a local document+-- handle with one prefix or to an absolute URI with an explicitly allowed+-- scheme. External targets are never resolved by okf.+data HandleReferenceRule = HandleReferenceRule+  { localPrefix :: !Text,+    externalUriSchemes :: ![Text],+    allowSelf :: !Bool+  }+  deriving stock (Generic, Eq, Ord, Show)+  deriving anyclass (FromDhall)++-- | A field whose values name a path or URI per OKF v0.2 specification §6.2: an+-- absolute URL, a bundle-relative path beginning with @\/@, or an ordinary+-- relative path resolved against the concept's own directory.+--+-- Deliberately distinct from 'HandleReferenceRule'. A handle resolves against+-- the bundle's document-ID index and fails by carrying the wrong prefix or+-- having no owner; a path resolves against the concept tree and fails by not+-- being a §6.2 shape, by climbing above the bundle root, or by naming a concept+-- that is not there. Declaring both on one rule is a definition error.+--+-- An empty @externalUriSchemes@ means no absolute URL is permitted at all, so a+-- separate "must be a path, never a URL" flag would say nothing new. Which+-- bundle paths okf can resolve depends on the entry point: 'validateProfileWith'+-- resolves every file the bundle holds, including §6.3's+-- @references\/attesters\/revenue.py@, while 'validateProfile' is handed+-- concepts alone and so resolves @.md@ targets only.+data PathReferenceRule = PathReferenceRule+  { externalUriSchemes :: ![Text],+    allowSelf :: !Bool+  }+  deriving stock (Generic, Eq, Ord, Show)+  deriving anyclass (FromDhall)++-- | One documented frontmatter key. The description is prose for humans and is+-- never checked against a bundle.+--+-- @elementFields@ and @objectFields@ describe two different shapes.+-- @elementFields@ constrains the record inside /each element of a list/;+-- @objectFields@ constrains the record that /is/ the value. Declaring both means+-- either spelling is accepted and both are checked against the same member+-- rules, which is how a profile describes the OKF v0.2 @verified@ key.+data FieldRule = FieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe FieldFormat),+    elementFields :: !(Maybe NestedRules),+    objectFields :: !(Maybe NestedRules),+    reference :: !(Maybe HandleReferenceRule),+    path :: !(Maybe PathReferenceRule),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | Rules for the flat object stored in each element of a list-valued field, or+-- in the mapping that is the value of an object-valued field. The nested rule+-- type has neither an @elementFields@ nor an @objectFields@ member, which makes+-- the public descriptor depth-bounded rather than recursive.+data NestedRules = NestedRules+  { required :: ![NestedFieldRule],+    recommended :: ![NestedFieldRule],+    optional :: ![NestedFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | One field inside a list element record or an object-valued mapping. It+-- carries @path@ because @sources[].resource@ is the motivating path-valued+-- field of §6.2 and lives inside a list element; it deliberately carries no+-- @reference@, because no v0.2 field names a document handle at nested scope.+data NestedFieldRule = NestedFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe FieldFormat),+    path :: !(Maybe PathReferenceRule),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | Whether a key must be a single value, a non-empty list, a mapping, or any+-- of them. 'Object' is placed last so the derived 'Ord' keeps the relative+-- order of the three published alternatives, which the definition-error sort key+-- relies on.+data Cardinality = Any | Scalar | List | Object+  deriving stock (Generic, Eq, Ord, Show)++-- | Decoded from the three-alternative published union in+-- @okf-core\/dhall\/Cardinality.dhall@. 'Object' is deliberately unreachable+-- from Dhall: it is produced only by compilation, when a rule declares+-- @objectFields@. Adding an alternative to the published union would change the+-- type of every value written against it and would break descriptors pinned to+-- the previous schema, which no record-level fallback decoder can repair,+-- because every frozen generation in the chain refers to this same type. An+-- author who wants to say "this key must be a mapping" and nothing more writes+-- @objectFields = Some NestedRules::{=}@.+instance FromDhall Cardinality where+  autoWith _normalizer =+    Dhall.union+      ( (Any <$ Dhall.constructor "Any" Dhall.unit)+          <> (Scalar <$ Dhall.constructor "Scalar" Dhall.unit)+          <> (List <$ Dhall.constructor "List" Dhall.unit)+      )++-- | A named value format. Formats constrain present values but do not imply+-- that a field must be present.+--+-- The first five constrain text. 'Actor' and 'HumanActor' constrain text against+-- the OKF v0.2 actor convention of specification §7, classified by+-- 'Okf.Actor.parseActor'. 'Integer', 'NonNegativeInteger', and 'Boolean'+-- constrain a value that is not text at all; declaring one of them refines an+-- unspecified cardinality to 'Scalar', because otherwise a numeric or boolean+-- key is reported missing before its value is ever examined.+--+-- The OKF v0.2 alternatives are appended after 'DocumentHandle' so the derived+-- 'Ord' keeps the relative order of the original five, which the+-- definition-error sort key relies on.+data FieldFormat+  = Rfc3339Utc+  | Date+  | Uri+  | UriWithScheme Text+  | DocumentHandle Text+  | Actor+  | HumanActor+  | Integer+  | NonNegativeInteger+  | Boolean+  deriving stock (Generic, Eq, Ord, Show)+  deriving anyclass (FromDhall)++-- | One rule per allowed concept @type@ string.+data TypeRule = TypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !FrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++-- | Decode @type_@ from the Dhall field @type@ by stripping the trailing+-- underscore; all other fields map by their exact name. (Mirrors how+-- 'Okf.Bundle' uses a @type_@ field to avoid clashing with the @type@ keyword.)+instance FromDhall TypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | Encode a profile so tooling can consume the same descriptor okf reads.+-- Written by hand rather than derived so the key order is stable and, more+-- importantly, so 'TypeRule' emits @type@ rather than the Haskell field name+-- @type_@ — matching the Dhall field and how 'Okf.Graph.Node' already encodes.+instance ToJSON ProfileSpec where+  toJSON ProfileSpec {name, description, okfVersion, frontmatter, allowUnknownTypes, allowUnknownFields, idField, requireBundleVersion, types = typeRules} =+    object+      [ "name" .= name,+        "description" .= description,+        "okfVersion" .= okfVersion,+        "requireBundleVersion" .= requireBundleVersion,+        "allowUnknownTypes" .= allowUnknownTypes,+        "allowUnknownFields" .= allowUnknownFields,+        "idField" .= idField,+        "frontmatter" .= frontmatter,+        "types" .= typeRules+      ]++instance ToJSON FrontmatterRules where+  toJSON FrontmatterRules {required, recommended, optional} =+    object+      [ "required" .= required,+        "recommended" .= recommended,+        "optional" .= optional+      ]++instance ToJSON FieldCondition where+  toJSON FieldCondition {field = fieldName, hasValue} =+    object+      [ "field" .= fieldName,+        "hasValue" .= hasValue+      ]++instance ToJSON HandleReferenceRule where+  toJSON HandleReferenceRule {localPrefix, externalUriSchemes, allowSelf} =+    object+      [ "localPrefix" .= localPrefix,+        "externalUriSchemes" .= externalUriSchemes,+        "allowSelf" .= allowSelf+      ]++instance ToJSON PathReferenceRule where+  toJSON PathReferenceRule {externalUriSchemes, allowSelf} =+    object+      [ "externalUriSchemes" .= externalUriSchemes,+        "allowSelf" .= allowSelf+      ]++instance ToJSON FieldRule where+  toJSON FieldRule {field = fieldName, description, allowedValues, cardinality, format, elementFields, objectFields, reference, path = pathRule, when = condition} =+    object+      [ "field" .= fieldName,+        "description" .= description,+        "allowedValues" .= allowedValues,+        "cardinality" .= cardinality,+        "format" .= format,+        "elementFields" .= elementFields,+        "reference" .= reference,+        "when" .= condition,+        -- Appended rather than placed beside @elementFields@, so that the list+        -- reads as "the keys this instance has always emitted, then the ones+        -- added since". A consumer keys on names, not position.+        "objectFields" .= objectFields,+        "path" .= pathRule+      ]++instance ToJSON NestedRules where+  toJSON NestedRules {required, recommended, optional} =+    object+      [ "required" .= required,+        "recommended" .= recommended,+        "optional" .= optional+      ]++instance ToJSON NestedFieldRule where+  toJSON NestedFieldRule {field = fieldName, description, allowedValues, cardinality, format, path = pathRule, when = condition} =+    object+      [ "field" .= fieldName,+        "description" .= description,+        "allowedValues" .= allowedValues,+        "cardinality" .= cardinality,+        "format" .= format,+        "when" .= condition,+        -- Appended for the same reason 'FieldRule' appends @objectFields@.+        "path" .= pathRule+      ]++instance ToJSON Cardinality where+  toJSON = String . cardinalityName++cardinalityName :: Cardinality -> Text+cardinalityName = \case+  Any -> "any"+  Scalar -> "scalar"+  List -> "list"+  Object -> "object"++instance ToJSON FieldFormat where+  toJSON = \case+    Rfc3339Utc -> String "rfc3339-utc"+    Date -> String "date"+    Uri -> String "uri"+    UriWithScheme scheme -> object ["uriWithScheme" .= scheme]+    DocumentHandle prefix -> object ["documentHandle" .= prefix]+    Actor -> String "actor"+    HumanActor -> String "human-actor"+    Integer -> String "integer"+    NonNegativeInteger -> String "non-negative-integer"+    Boolean -> String "boolean"++instance ToJSON TypeRule where+  toJSON+    TypeRule+      { type_ = ruleType,+        description,+        frontmatter,+        pathPattern,+        resourceScheme,+        requireSchemaSection,+        schemaColumns,+        idPrefix+      } =+      object+        [ "type" .= ruleType,+          "description" .= description,+          "frontmatter" .= frontmatter,+          "pathPattern" .= pathPattern,+          "resourceScheme" .= resourceScheme,+          "requireSchemaSection" .= requireSchemaSection,+          "schemaColumns" .= schemaColumns,+          "idPrefix" .= idPrefix+        ]++-- | The okf 0.2.x profile record: frontmatter keys were bare strings and+-- nothing carried a description. Decoded only as a fallback, so descriptors+-- written before descriptions existed keep loading unchanged. Deliberately+-- private and deliberately frozen — it is a record of a retired shape, not a+-- second profile model. Exercised by+-- @okf-core\/test\/fixtures\/profiles\/legacy-0.2.dhall@.+data LegacyProfileSpec = LegacyProfileSpec+  { name :: !Text,+    okfVersion :: !Text,+    frontmatter :: !LegacyFrontmatterRules,+    allowUnknownTypes :: !Bool,+    idField :: !(Maybe Text),+    types :: ![LegacyTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | The okf 0.2.x frontmatter record: two lists of bare key names.+data LegacyFrontmatterRules = LegacyFrontmatterRules+  { required :: ![Text],+    recommended :: ![Text]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | The okf 0.2.x per-@type@ rule: today's 'TypeRule' without descriptions or+-- type-specific frontmatter.+data LegacyTypeRule = LegacyTypeRule+  { type_ :: !Text,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall LegacyTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | The five-alternative published format union, frozen before the OKF v0.2+-- value formats were added.+--+-- Unlike every other frozen shape below this is a /union/ rather than a record.+-- A Dhall union value carries its full alternative set in its type, so a+-- descriptor pinned to the five-alternative+-- @okf-core\/dhall\/FieldFormat.dhall@ does not typecheck against the current+-- decoder, and no record-level fallback can repair that: every frozen generation+-- would still refer to the widened 'FieldFormat'. Every frozen generation below+-- therefore refers to this type instead.+--+-- The instance is hand-written rather than derived so that the Dhall alternative+-- names stay @Rfc3339Utc@ and friends while the Haskell constructors stay+-- distinct from the current type's.+data PreV02FieldFormat+  = LegacyRfc3339Utc+  | LegacyDate+  | LegacyUri+  | LegacyUriWithScheme Text+  | LegacyDocumentHandle Text+  deriving stock (Generic, Eq, Ord, Show)++instance FromDhall PreV02FieldFormat where+  autoWith _normalizer =+    Dhall.union+      ( (LegacyRfc3339Utc <$ Dhall.constructor "Rfc3339Utc" Dhall.unit)+          <> (LegacyDate <$ Dhall.constructor "Date" Dhall.unit)+          <> (LegacyUri <$ Dhall.constructor "Uri" Dhall.unit)+          <> (LegacyUriWithScheme <$> Dhall.constructor "UriWithScheme" Dhall.auto)+          <> (LegacyDocumentHandle <$> Dhall.constructor "DocumentHandle" Dhall.auto)+      )++upgradePreV02FieldFormat :: PreV02FieldFormat -> FieldFormat+upgradePreV02FieldFormat = \case+  LegacyRfc3339Utc -> Rfc3339Utc+  LegacyDate -> Date+  LegacyUri -> Uri+  LegacyUriWithScheme scheme -> UriWithScheme scheme+  LegacyDocumentHandle prefix -> DocumentHandle prefix++-- | The complete descriptor generation frozen before a profile could require its+-- bundle to declare an OKF version. This is the immediately preceding public+-- descriptor generation: it is today's shape minus the @requireBundleVersion@+-- member on the top-level record. That member is the only difference, so every+-- rule record, every type rule, and every union is unchanged and is shared+-- rather than copied — the freezing rule of+-- @docs\/adr\/11-growing-the-profile-descriptor-language.md@ is about the+-- descriptor as a whole, and a generation that changes one record copies only+-- what changed. Exercised by+-- @okf-core\/test\/fixtures\/profiles\/pre-bundle-version.dhall@.+data PreBundleVersionProfileSpec = PreBundleVersionProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !FrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    types :: ![TypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | The complete descriptor generation frozen before path-valued reference+-- rules were added: today's shape minus the @path@ member on 'FieldRule' and on+-- 'NestedFieldRule'. Because that is a record addition rather than a union+-- widening, 'Cardinality', 'FieldFormat', 'FieldCondition', and+-- 'HandleReferenceRule' are unchanged by it and so are shared rather than+-- copied; the two rule records and everything that contains them are copied.+-- Exercised by @okf-core\/test\/fixtures\/profiles\/path-references-mp8-ep3.dhall@.+data PrePathProfileFieldRule = PrePathProfileFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe FieldFormat),+    elementFields :: !(Maybe PrePathProfileNestedRules),+    objectFields :: !(Maybe PrePathProfileNestedRules),+    reference :: !(Maybe HandleReferenceRule),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PrePathProfileNestedRules = PrePathProfileNestedRules+  { required :: ![PrePathProfileNestedFieldRule],+    recommended :: ![PrePathProfileNestedFieldRule],+    optional :: ![PrePathProfileNestedFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PrePathProfileNestedFieldRule = PrePathProfileNestedFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe FieldFormat),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PrePathProfileFrontmatterRules = PrePathProfileFrontmatterRules+  { required :: ![PrePathProfileFieldRule],+    recommended :: ![PrePathProfileFieldRule],+    optional :: ![PrePathProfileFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PrePathProfileSpec = PrePathProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !PrePathProfileFrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    types :: ![PrePathProfileTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PrePathProfileTypeRule = PrePathProfileTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !PrePathProfileFrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall PrePathProfileTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | The complete object-rule descriptor generation, frozen before the OKF v0.2+-- value formats were added to 'FieldFormat'. Its records match the shape+-- 'PrePathProfileFieldRule' froze — no @path@ member — and the further+-- difference is that every @format@ member refers to the frozen+-- five-alternative 'PreV02FieldFormat'. Exercised by+-- @okf-core\/test\/fixtures\/profiles\/formats-mp8-ep2.dhall@.+data PreActorProfileFieldRule = PreActorProfileFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat),+    elementFields :: !(Maybe PreActorProfileNestedRules),+    objectFields :: !(Maybe PreActorProfileNestedRules),+    reference :: !(Maybe HandleReferenceRule),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreActorProfileNestedRules = PreActorProfileNestedRules+  { required :: ![PreActorProfileNestedFieldRule],+    recommended :: ![PreActorProfileNestedFieldRule],+    optional :: ![PreActorProfileNestedFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreActorProfileNestedFieldRule = PreActorProfileNestedFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreActorProfileFrontmatterRules = PreActorProfileFrontmatterRules+  { required :: ![PreActorProfileFieldRule],+    recommended :: ![PreActorProfileFieldRule],+    optional :: ![PreActorProfileFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreActorProfileSpec = PreActorProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !PreActorProfileFrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    types :: ![PreActorProfileTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreActorProfileTypeRule = PreActorProfileTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !PreActorProfileFrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall PreActorProfileTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | The complete optional-presence descriptor generation, frozen before object+-- rules were added: it matches the shape before @objectFields@ was added to+-- 'FieldRule'. 'Cardinality', 'HandleReferenceRule', and 'FieldCondition' are+-- unchanged by every addition since and so are shared rather than copied; the+-- nested rule types are copied because their @format@ member now refers to the+-- frozen 'PreV02FieldFormat'. Exercised by+-- @okf-core\/test\/fixtures\/profiles\/object-fields-mp8-ep1.dhall@.+data PreObjectProfileFieldRule = PreObjectProfileFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat),+    elementFields :: !(Maybe PreObjectProfileNestedRules),+    reference :: !(Maybe HandleReferenceRule),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreObjectProfileNestedRules = PreObjectProfileNestedRules+  { required :: ![PreObjectProfileNestedFieldRule],+    recommended :: ![PreObjectProfileNestedFieldRule],+    optional :: ![PreObjectProfileNestedFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreObjectProfileNestedFieldRule = PreObjectProfileNestedFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreObjectProfileFrontmatterRules = PreObjectProfileFrontmatterRules+  { required :: ![PreObjectProfileFieldRule],+    recommended :: ![PreObjectProfileFieldRule],+    optional :: ![PreObjectProfileFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreObjectProfileSpec = PreObjectProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !PreObjectProfileFrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    types :: ![PreObjectProfileTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreObjectProfileTypeRule = PreObjectProfileTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !PreObjectProfileFrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall PreObjectProfileTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | The complete reference-aware descriptor generation, frozen before the+-- @optional@ presence list was added to 'FrontmatterRules' and 'NestedRules'.+-- This is the immediately preceding public descriptor generation: it matches+-- today's shape exactly apart from that third list, so every descriptor written+-- as a record literal against the published schema keeps loading. Exercised by+-- @okf-core\/test\/fixtures\/profiles\/document-references-ep3.dhall@.+data ReferenceProfileFieldRule = ReferenceProfileFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat),+    elementFields :: !(Maybe ReferenceProfileNestedRules),+    reference :: !(Maybe HandleReferenceRule),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data ReferenceProfileNestedRules = ReferenceProfileNestedRules+  { required :: ![ReferenceProfileNestedFieldRule],+    recommended :: ![ReferenceProfileNestedFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data ReferenceProfileNestedFieldRule = ReferenceProfileNestedFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data ReferenceProfileFrontmatterRules = ReferenceProfileFrontmatterRules+  { required :: ![ReferenceProfileFieldRule],+    recommended :: ![ReferenceProfileFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data ReferenceProfileSpec = ReferenceProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !ReferenceProfileFrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    types :: ![ReferenceProfileTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data ReferenceProfileTypeRule = ReferenceProfileTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !ReferenceProfileFrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall ReferenceProfileTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | The complete condition-aware descriptor generation, frozen before+-- top-level document-reference policies were added.+data ConditionalProfileFieldRule = ConditionalProfileFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat),+    elementFields :: !(Maybe ConditionalProfileNestedRules),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data ConditionalProfileNestedRules = ConditionalProfileNestedRules+  { required :: ![ConditionalProfileNestedFieldRule],+    recommended :: ![ConditionalProfileNestedFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data ConditionalProfileNestedFieldRule = ConditionalProfileNestedFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat),+    when :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data ConditionalProfileFrontmatterRules = ConditionalProfileFrontmatterRules+  { required :: ![ConditionalProfileFieldRule],+    recommended :: ![ConditionalProfileFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data ConditionalProfileSpec = ConditionalProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !ConditionalProfileFrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    types :: ![ConditionalProfileTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data ConditionalProfileTypeRule = ConditionalProfileTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !ConditionalProfileFrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall ConditionalProfileTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | The complete bounded-nested descriptor generation, frozen before+-- same-scope field conditions were added. This is the immediately preceding+-- public descriptor generation.+data NestedProfileFieldRule = NestedProfileFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat),+    elementFields :: !(Maybe NestedProfileRules)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data NestedProfileRules = NestedProfileRules+  { required :: ![NestedProfileNestedFieldRule],+    recommended :: ![NestedProfileNestedFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data NestedProfileNestedFieldRule = NestedProfileNestedFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data NestedProfileFrontmatterRules = NestedProfileFrontmatterRules+  { required :: ![NestedProfileFieldRule],+    recommended :: ![NestedProfileFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data NestedProfileSpec = NestedProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !NestedProfileFrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    types :: ![NestedProfileTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data NestedProfileTypeRule = NestedProfileTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !NestedProfileFrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall NestedProfileTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | The complete EP-4 field rule, frozen before one-level nested records were+-- added. This is the immediately preceding public descriptor generation.+data FormatFieldRule = FormatFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe PreV02FieldFormat)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data FormatFrontmatterRules = FormatFrontmatterRules+  { required :: ![FormatFieldRule],+    recommended :: ![FormatFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data FormatProfileSpec = FormatProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !FormatFrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    types :: ![FormatTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data FormatTypeRule = FormatTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !FormatFrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall FormatTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | The EP-3 field rule, frozen before named formats were added.+data CardinalityFieldRule = CardinalityFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data CardinalityFrontmatterRules = CardinalityFrontmatterRules+  { required :: ![CardinalityFieldRule],+    recommended :: ![CardinalityFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | The complete EP-3 profile shape, frozen before named formats were added.+data CardinalityProfileSpec = CardinalityProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !CardinalityFrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    types :: ![CardinalityTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data CardinalityTypeRule = CardinalityTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !CardinalityFrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall CardinalityTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | The EP-2 field rule, frozen before cardinality was added.+data VocabularyFieldRule = VocabularyFieldRule+  { field :: !Text,+    description :: !(Maybe Text),+    allowedValues :: ![Text]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data VocabularyFrontmatterRules = VocabularyFrontmatterRules+  { required :: ![VocabularyFieldRule],+    recommended :: ![VocabularyFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | The EP-2 profile shape, frozen before cardinality was added.+data VocabularyProfileSpec = VocabularyProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !VocabularyFrontmatterRules,+    allowUnknownTypes :: !Bool,+    allowUnknownFields :: !Bool,+    idField :: !(Maybe Text),+    types :: ![VocabularyTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data VocabularyTypeRule = VocabularyTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !VocabularyFrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall VocabularyTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | A field rule from either self-documenting schema generation, before value+-- vocabularies were added.+data PreviousFieldRule = PreviousFieldRule+  { field :: !Text,+    description :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data PreviousFrontmatterRules = PreviousFrontmatterRules+  { required :: ![PreviousFieldRule],+    recommended :: ![PreviousFieldRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++-- | The type-aware shape from EP-1, frozen before vocabularies and field-name+-- closure were added.+data TypeAwareProfileSpec = TypeAwareProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !PreviousFrontmatterRules,+    allowUnknownTypes :: !Bool,+    idField :: !(Maybe Text),+    types :: ![TypeAwareTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data TypeAwareTypeRule = TypeAwareTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    frontmatter :: !PreviousFrontmatterRules,+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall TypeAwareTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++-- | The self-documenting profile shape published immediately before+-- type-specific frontmatter rules. It is frozen as a compatibility decoder in+-- exactly the same way as the older 0.2.x shape below.+data DescribedProfileSpec = DescribedProfileSpec+  { name :: !Text,+    description :: !(Maybe Text),+    okfVersion :: !Text,+    frontmatter :: !PreviousFrontmatterRules,+    allowUnknownTypes :: !Bool,+    idField :: !(Maybe Text),+    types :: ![DescribedTypeRule]+  }+  deriving stock (Generic, Eq, Show)+  deriving anyclass (FromDhall)++data DescribedTypeRule = DescribedTypeRule+  { type_ :: !Text,+    description :: !(Maybe Text),+    pathPattern :: !(Maybe Text),+    resourceScheme :: !(Maybe Text),+    requireSchemaSection :: !Bool,+    schemaColumns :: ![Text],+    idPrefix :: !(Maybe Text)+  }+  deriving stock (Generic, Eq, Show)++instance FromDhall DescribedTypeRule where+  autoWith _normalizer =+    genericAutoWith+      (Dhall.defaultInterpretOptions {Dhall.fieldModifier = stripTrailingUnderscore})+    where+      stripTrailingUnderscore fieldName =+        fromMaybe fieldName (Text.stripSuffix "_" fieldName)++emptyFrontmatterRules :: FrontmatterRules+emptyFrontmatterRules = FrontmatterRules {required = [], recommended = [], optional = []}++upgradePrePathProfileFrontmatter :: PrePathProfileFrontmatterRules -> FrontmatterRules+upgradePrePathProfileFrontmatter previous =+  FrontmatterRules+    { required = map upgradeField (previous ^. #required),+      recommended = map upgradeField (previous ^. #recommended),+      optional = map upgradeField (previous ^. #optional)+    }+  where+    upgradeField rule =+      FieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = rule ^. #format,+          elementFields = upgradeNestedRules <$> rule ^. #elementFields,+          objectFields = upgradeNestedRules <$> rule ^. #objectFields,+          reference = rule ^. #reference,+          path = Nothing,+          when = rule ^. #when+        }+    upgradeNestedRules rules =+      NestedRules+        { required = map upgradeNestedField (rules ^. #required),+          recommended = map upgradeNestedField (rules ^. #recommended),+          optional = map upgradeNestedField (rules ^. #optional)+        }+    upgradeNestedField rule =+      NestedFieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = rule ^. #format,+          path = Nothing,+          when = rule ^. #when+        }++upgradePreActorProfileFrontmatter :: PreActorProfileFrontmatterRules -> FrontmatterRules+upgradePreActorProfileFrontmatter previous =+  FrontmatterRules+    { required = map upgradeField (previous ^. #required),+      recommended = map upgradeField (previous ^. #recommended),+      optional = map upgradeField (previous ^. #optional)+    }+  where+    upgradeField rule =+      FieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          elementFields = upgradeNestedRules <$> rule ^. #elementFields,+          objectFields = upgradeNestedRules <$> rule ^. #objectFields,+          reference = rule ^. #reference,+          path = Nothing,+          when = rule ^. #when+        }+    upgradeNestedRules rules =+      NestedRules+        { required = map upgradeNestedField (rules ^. #required),+          recommended = map upgradeNestedField (rules ^. #recommended),+          optional = map upgradeNestedField (rules ^. #optional)+        }+    upgradeNestedField rule =+      NestedFieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          path = Nothing,+          when = rule ^. #when+        }++upgradePreObjectProfileFrontmatter :: PreObjectProfileFrontmatterRules -> FrontmatterRules+upgradePreObjectProfileFrontmatter previous =+  FrontmatterRules+    { required = map upgradeField (previous ^. #required),+      recommended = map upgradeField (previous ^. #recommended),+      optional = map upgradeField (previous ^. #optional)+    }+  where+    upgradeField rule =+      FieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          elementFields = upgradeNestedRules <$> rule ^. #elementFields,+          objectFields = Nothing,+          reference = rule ^. #reference,+          path = Nothing,+          when = rule ^. #when+        }+    upgradeNestedRules rules =+      NestedRules+        { required = map upgradeNestedField (rules ^. #required),+          recommended = map upgradeNestedField (rules ^. #recommended),+          optional = map upgradeNestedField (rules ^. #optional)+        }+    upgradeNestedField rule =+      NestedFieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          path = Nothing,+          when = rule ^. #when+        }++upgradeReferenceProfileFrontmatter :: ReferenceProfileFrontmatterRules -> FrontmatterRules+upgradeReferenceProfileFrontmatter previous =+  FrontmatterRules+    { required = map upgradeField (previous ^. #required),+      recommended = map upgradeField (previous ^. #recommended),+      optional = []+    }+  where+    upgradeField rule =+      FieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          elementFields = upgradeNestedRules <$> rule ^. #elementFields,+          objectFields = Nothing,+          reference = rule ^. #reference,+          path = Nothing,+          when = rule ^. #when+        }+    upgradeNestedRules rules =+      NestedRules+        { required = map upgradeNestedField (rules ^. #required),+          recommended = map upgradeNestedField (rules ^. #recommended),+          optional = []+        }+    upgradeNestedField rule =+      NestedFieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          path = Nothing,+          when = rule ^. #when+        }++upgradePreviousFrontmatter :: PreviousFrontmatterRules -> FrontmatterRules+upgradePreviousFrontmatter previous =+  FrontmatterRules+    { required = map upgradeField (previous ^. #required),+      recommended = map upgradeField (previous ^. #recommended),+      optional = []+    }+  where+    upgradeField rule =+      FieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = [],+          cardinality = Any,+          format = Nothing,+          elementFields = Nothing,+          objectFields = Nothing,+          reference = Nothing,+          path = Nothing,+          when = Nothing+        }++upgradeConditionalProfileFrontmatter :: ConditionalProfileFrontmatterRules -> FrontmatterRules+upgradeConditionalProfileFrontmatter previous =+  FrontmatterRules+    { required = map upgradeField (previous ^. #required),+      recommended = map upgradeField (previous ^. #recommended),+      optional = []+    }+  where+    upgradeField rule =+      FieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          elementFields = upgradeNestedRules <$> rule ^. #elementFields,+          objectFields = Nothing,+          reference = Nothing,+          path = Nothing,+          when = rule ^. #when+        }+    upgradeNestedRules rules =+      NestedRules+        { required = map upgradeNestedField (rules ^. #required),+          recommended = map upgradeNestedField (rules ^. #recommended),+          optional = []+        }+    upgradeNestedField rule =+      NestedFieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          path = Nothing,+          when = rule ^. #when+        }++upgradeNestedProfileFrontmatter :: NestedProfileFrontmatterRules -> FrontmatterRules+upgradeNestedProfileFrontmatter previous =+  FrontmatterRules+    { required = map upgradeField (previous ^. #required),+      recommended = map upgradeField (previous ^. #recommended),+      optional = []+    }+  where+    upgradeField rule =+      FieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          elementFields = upgradeNestedProfileRules <$> rule ^. #elementFields,+          objectFields = Nothing,+          reference = Nothing,+          path = Nothing,+          when = Nothing+        }+    upgradeNestedProfileRules rules =+      NestedRules+        { required = map upgradeNestedField (rules ^. #required),+          recommended = map upgradeNestedField (rules ^. #recommended),+          optional = []+        }+    upgradeNestedField rule =+      NestedFieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          path = Nothing,+          when = Nothing+        }++upgradeFormatFrontmatter :: FormatFrontmatterRules -> FrontmatterRules+upgradeFormatFrontmatter previous =+  FrontmatterRules+    { required = map upgradeField (previous ^. #required),+      recommended = map upgradeField (previous ^. #recommended),+      optional = []+    }+  where+    upgradeField rule =+      FieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = upgradePreV02FieldFormat <$> rule ^. #format,+          elementFields = Nothing,+          objectFields = Nothing,+          reference = Nothing,+          path = Nothing,+          when = Nothing+        }++upgradeCardinalityFrontmatter :: CardinalityFrontmatterRules -> FrontmatterRules+upgradeCardinalityFrontmatter previous =+  FrontmatterRules+    { required = map upgradeField (previous ^. #required),+      recommended = map upgradeField (previous ^. #recommended),+      optional = []+    }+  where+    upgradeField rule =+      FieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = rule ^. #cardinality,+          format = Nothing,+          elementFields = Nothing,+          objectFields = Nothing,+          reference = Nothing,+          path = Nothing,+          when = Nothing+        }++upgradeVocabularyFrontmatter :: VocabularyFrontmatterRules -> FrontmatterRules+upgradeVocabularyFrontmatter previous =+  FrontmatterRules+    { required = map upgradeField (previous ^. #required),+      recommended = map upgradeField (previous ^. #recommended),+      optional = []+    }+  where+    upgradeField rule =+      FieldRule+        { field = rule ^. #field,+          description = rule ^. #description,+          allowedValues = rule ^. #allowedValues,+          cardinality = Any,+          format = Nothing,+          elementFields = Nothing,+          objectFields = Nothing,+          reference = Nothing,+          path = Nothing,+          when = Nothing+        }++-- | Lift the generation frozen before @requireBundleVersion@ forward. Every rule+-- record is shared with today's schema, so this copies members across and+-- supplies the one no-op default: a descriptor that predates the member demands+-- nothing of its bundle's version declaration, which is what it meant when it+-- was written.+upgradePreBundleVersionProfile :: PreBundleVersionProfileSpec -> ProfileSpec+upgradePreBundleVersionProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = previous ^. #frontmatter,+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = previous ^. #allowUnknownFields,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = previous ^. #types+    }++upgradePrePathProfile :: PrePathProfileSpec -> ProfileSpec+upgradePrePathProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = upgradePrePathProfileFrontmatter (previous ^. #frontmatter),+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = previous ^. #allowUnknownFields,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (previous ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = upgradePrePathProfileFrontmatter (rule ^. #frontmatter),+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++upgradePreActorProfile :: PreActorProfileSpec -> ProfileSpec+upgradePreActorProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = upgradePreActorProfileFrontmatter (previous ^. #frontmatter),+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = previous ^. #allowUnknownFields,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (previous ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = upgradePreActorProfileFrontmatter (rule ^. #frontmatter),+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++upgradePreObjectProfile :: PreObjectProfileSpec -> ProfileSpec+upgradePreObjectProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = upgradePreObjectProfileFrontmatter (previous ^. #frontmatter),+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = previous ^. #allowUnknownFields,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (previous ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = upgradePreObjectProfileFrontmatter (rule ^. #frontmatter),+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++upgradeReferenceProfile :: ReferenceProfileSpec -> ProfileSpec+upgradeReferenceProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = upgradeReferenceProfileFrontmatter (previous ^. #frontmatter),+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = previous ^. #allowUnknownFields,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (previous ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = upgradeReferenceProfileFrontmatter (rule ^. #frontmatter),+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++upgradeConditionalProfile :: ConditionalProfileSpec -> ProfileSpec+upgradeConditionalProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = upgradeConditionalProfileFrontmatter (previous ^. #frontmatter),+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = previous ^. #allowUnknownFields,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (previous ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = upgradeConditionalProfileFrontmatter (rule ^. #frontmatter),+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++upgradeNestedProfile :: NestedProfileSpec -> ProfileSpec+upgradeNestedProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = upgradeNestedProfileFrontmatter (previous ^. #frontmatter),+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = previous ^. #allowUnknownFields,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (previous ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = upgradeNestedProfileFrontmatter (rule ^. #frontmatter),+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++upgradeFormatProfile :: FormatProfileSpec -> ProfileSpec+upgradeFormatProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = upgradeFormatFrontmatter (previous ^. #frontmatter),+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = previous ^. #allowUnknownFields,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (previous ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = upgradeFormatFrontmatter (rule ^. #frontmatter),+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++upgradeCardinalityProfile :: CardinalityProfileSpec -> ProfileSpec+upgradeCardinalityProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = upgradeCardinalityFrontmatter (previous ^. #frontmatter),+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = previous ^. #allowUnknownFields,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (previous ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = upgradeCardinalityFrontmatter (rule ^. #frontmatter),+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++upgradeVocabularyProfile :: VocabularyProfileSpec -> ProfileSpec+upgradeVocabularyProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = upgradeVocabularyFrontmatter (previous ^. #frontmatter),+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = previous ^. #allowUnknownFields,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (previous ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = upgradeVocabularyFrontmatter (rule ^. #frontmatter),+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++upgradeTypeAwareProfile :: TypeAwareProfileSpec -> ProfileSpec+upgradeTypeAwareProfile previous =+  ProfileSpec+    { name = previous ^. #name,+      description = previous ^. #description,+      okfVersion = previous ^. #okfVersion,+      frontmatter = upgradePreviousFrontmatter (previous ^. #frontmatter),+      allowUnknownTypes = previous ^. #allowUnknownTypes,+      allowUnknownFields = True,+      idField = previous ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (previous ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = upgradePreviousFrontmatter (rule ^. #frontmatter),+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++upgradeDescribedProfile :: DescribedProfileSpec -> ProfileSpec+upgradeDescribedProfile described =+  ProfileSpec+    { name = described ^. #name,+      description = described ^. #description,+      okfVersion = described ^. #okfVersion,+      frontmatter = upgradePreviousFrontmatter (described ^. #frontmatter),+      allowUnknownTypes = described ^. #allowUnknownTypes,+      allowUnknownFields = True,+      idField = described ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (described ^. #types)+    }+  where+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = rule ^. #description,+          frontmatter = emptyFrontmatterRules,+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++-- | Lift a 0.2.x profile into the current shape by attaching no descriptions+-- and empty type-specific frontmatter.+upgradeLegacyProfile :: LegacyProfileSpec -> ProfileSpec+upgradeLegacyProfile legacy =+  ProfileSpec+    { name = legacy ^. #name,+      description = Nothing,+      okfVersion = legacy ^. #okfVersion,+      frontmatter =+        FrontmatterRules+          { required = map undocumented (legacy ^. #frontmatter . #required),+            recommended = map undocumented (legacy ^. #frontmatter . #recommended),+            optional = []+          },+      allowUnknownTypes = legacy ^. #allowUnknownTypes,+      allowUnknownFields = True,+      idField = legacy ^. #idField,+      requireBundleVersion = Nothing,+      types = map upgradeRule (legacy ^. #types)+    }+  where+    undocumented key = FieldRule {field = key, description = Nothing, allowedValues = [], cardinality = Any, format = Nothing, elementFields = Nothing, objectFields = Nothing, reference = Nothing, path = Nothing, when = Nothing}+    upgradeRule rule =+      TypeRule+        { type_ = rule ^. #type_,+          description = Nothing,+          frontmatter = emptyFrontmatterRules,+          pathPattern = rule ^. #pathPattern,+          resourceScheme = rule ^. #resourceScheme,+          requireSchemaSection = rule ^. #requireSchemaSection,+          schemaColumns = rule ^. #schemaColumns,+          idPrefix = rule ^. #idPrefix+        }++-- | Load and decode a Dhall profile descriptor from a file path. Any evaluation+-- or decoding failure is captured as a human-readable 'Left'.+--+-- The pre-bundle-version shape, pre-path shape, pre-actor shape, pre-object+-- shape, reference-aware shape,+-- condition-aware shape, bounded-nested shape, EP-4+-- format shape, EP-3 cardinality shape, EP-2 vocabulary shape, type-aware EP-1+-- shape, self-documenting shape, and okf 0.2.x shape are accepted by frozen+-- fallback decoders and upgraded+-- with their no-op defaults. When every decoder fails, the /current/ decoder's+-- error is reported.+loadProfileFile :: FilePath -> IO (Either Text ProfileSpec)+loadProfileFile path = do+  current <- tryDecode (Dhall.inputFile auto path)+  case current of+    Right spec -> pure (Right spec)+    -- Only the current decoder's error is kept. An author wants to know how+    -- their descriptor differs from today's schema, not from a retired one.+    Left currentError -> maybe (Left currentError) Right <$> firstFrozen frozenDecoders+  where+    -- Newest generation first. Each entry looks identical but is inferred at a+    -- distinct result type, fixed by the upgrade function it names; @auto@ then+    -- picks that generation's decoder. Adding a generation is one line here.+    frozenDecoders :: [IO (Maybe ProfileSpec)]+    frozenDecoders =+      [ attempt upgradePreBundleVersionProfile,+        attempt upgradePrePathProfile,+        attempt upgradePreActorProfile,+        attempt upgradePreObjectProfile,+        attempt upgradeReferenceProfile,+        attempt upgradeConditionalProfile,+        attempt upgradeNestedProfile,+        attempt upgradeFormatProfile,+        attempt upgradeCardinalityProfile,+        attempt upgradeVocabularyProfile,+        attempt upgradeTypeAwareProfile,+        attempt upgradeDescribedProfile,+        attempt upgradeLegacyProfile+      ]++    -- Short-circuiting, so a descriptor that decodes at the first frozen+    -- generation costs one extra parse rather than thirteen.+    firstFrozen :: [IO (Maybe ProfileSpec)] -> IO (Maybe ProfileSpec)+    firstFrozen [] = pure Nothing+    firstFrozen (decoder : remaining) =+      decoder >>= \case+        Just spec -> pure (Just spec)+        Nothing -> firstFrozen remaining++    attempt :: (FromDhall a) => (a -> ProfileSpec) -> IO (Maybe ProfileSpec)+    attempt upgrade = either (const Nothing) (Just . upgrade) <$> tryDecode (Dhall.inputFile auto path)++    tryDecode :: IO a -> IO (Either Text a)+    tryDecode action =+      (Right <$> action)+        `catch` \(exception :: SomeException) -> pure (Left (Text.pack (show exception)))++-- | Does an already-evaluated Dhall expression decode as a profile? Tries the+-- current schema, then the pre-bundle-version, pre-path, pre-actor, pre-object,+-- reference-aware,+-- condition-aware, bounded-nested, EP-4, EP-3, EP-2, EP-1, self-documenting, and+-- okf 0.2.x schemas, so the published @okf-profiles@ package still enumerates.+-- Uses 'Dhall.rawInput', which normalizes and runs the decoder's extractor+-- without throwing, which is what lets registry enumeration be pure.+decodeProfileExpr :: Expr Src Void -> Maybe ProfileSpec+decodeProfileExpr expression =+  Dhall.rawInput Dhall.auto expression+    <|> fmap upgradePreBundleVersionProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradePrePathProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradePreActorProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradePreObjectProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradeReferenceProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradeConditionalProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradeNestedProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradeFormatProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradeCardinalityProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradeVocabularyProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradeTypeAwareProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradeDescribedProfile (Dhall.rawInput Dhall.auto expression)+    <|> fmap upgradeLegacyProfile (Dhall.rawInput Dhall.auto expression)++-- | The description a profile attaches to a frontmatter key, looking in+-- @required@ first, then @recommended@, then @optional@. 'Nothing' when the key+-- is undocumented or absent from the profile entirely.+profileFieldDescription :: ProfileSpec -> Text -> Maybe Text+profileFieldDescription spec key =+  case [rule | rule <- rules, rule ^. #field == key] of+    (rule : _) -> rule ^. #description+    [] -> Nothing+  where+    rules =+      spec ^. #frontmatter . #required+        <> spec ^. #frontmatter . #recommended+        <> spec ^. #frontmatter . #optional++-- | A malformed profile definition. The optional type is absent for profile+-- scope and present for a type-specific scope. The list name is @required@,+-- @recommended@, or @optional@.+data ProfileDefinitionError+  = DuplicateTypeRule Text+  | DuplicateFieldRule (Maybe Text) Text Text+  | ConflictingFieldRequirement (Maybe Text) Text+  | UnsatisfiableVocabulary (Maybe Text) Text [Text] [Text]+  | ConflictingCardinality (Maybe Text) Text Cardinality Cardinality+  | ElementFieldsRequireList (Maybe Text) FieldPath Cardinality+  | InvalidFormatParameter FieldPath FieldFormat Text+  | ConflictingFieldFormat FieldPath FieldFormat FieldFormat+  | EmptyConditionValues (Maybe Text) FieldPath FieldPath+  | ConditionFieldNotDeclared (Maybe Text) FieldPath FieldPath+  | ConditionFieldNotScalar (Maybe Text) FieldPath FieldPath Cardinality+  | ConditionFieldOpenVocabulary (Maybe Text) FieldPath FieldPath+  | ConditionFieldHasUnreachableValues (Maybe Text) FieldPath FieldPath [Text] [Text]+  | SelfConditionalField (Maybe Text) FieldPath+  | InvalidReferencePrefix (Maybe Text) FieldPath Text+  | ReferencePrefixNotDeclared (Maybe Text) FieldPath Text+  | ReferenceRequiresIdField (Maybe Text) FieldPath+  | InvalidExternalReferenceScheme (Maybe Text) FieldPath Text+  | ConflictingReferencePrefix Text FieldPath Text Text+  | ReferenceWithFormat (Maybe Text) FieldPath FieldFormat+  | -- | an @optional@ rule carries a @when@ condition, which gates only presence+    -- and is therefore dead: an optional rule has no presence check at all+    OptionalFieldWithCondition (Maybe Text) FieldPath+  | -- | a rule declares @objectFields@ alongside an explicit scalar or list+    -- cardinality; an object is neither, so the pairing cannot be satisfied+    ObjectFieldsRequireObjectShape (Maybe Text) FieldPath Cardinality+  | -- | one rule declares both a document-handle policy and a path policy;+    -- a value cannot be resolved as both a handle and a path+    PathReferenceWithHandleReference (Maybe Text) FieldPath+  | -- | @okfVersion@ is not @\<major\>.\<minor\>@+    InvalidProfileOkfVersion Text+  | -- | @okfVersion@ names a major version okf does not implement, so okf cannot+    -- know which of its rules still hold+    ProfileOkfVersionNotUnderstood Text+  | -- | @requireBundleVersion@ is not @\<major\>.\<minor\>@, so no bundle+    -- declaration could ever be compared against it+    InvalidRequiredBundleVersion Text+  | -- | a required or recommended rule names a key the declared version+    -- supersedes (scope, path, declared version, version that superseded the key)+    FieldSupersededInOkfVersion (Maybe Text) FieldPath Text Text+  | -- | a rule names a value format introduced after the declared version+    -- (scope, path, format, declared version, version that introduced the format)+    FormatRequiresOkfVersion (Maybe Text) FieldPath FieldFormat Text Text+  deriving stock (Generic, Eq, Ord, Show)++-- | Whether a 'PresenceClause' demands a key or merely recommends it. There is+-- deliberately no @OptionalField@ constructor: an optional key is encoded as an+-- 'EffectiveFieldRule' with /no/ presence clauses at all.+data FieldRequirement = RecommendedField | RequiredField+  deriving stock (Generic, Eq, Ord, Show)++-- | One reason a key may have to be present, optionally gated by a condition on+-- another same-scope key. Abstract: read it with 'presenceClauseRequirement' and+-- 'presenceClauseCondition'.+data PresenceClause = PresenceClause+  { requirement :: !FieldRequirement,+    condition :: !(Maybe FieldCondition)+  }+  deriving stock (Generic, Eq, Show)++-- | Everything that actually applies to one frontmatter key for one concept+-- type: the profile-scope declaration merged with the type-scope one per+-- [ADR 5](docs/adr/5-compile-profile-rules-before-validation.md). Abstract: read+-- it with the @fieldRule*@ accessors below, never by pattern matching, so that+-- later profile features can extend it without breaking consumers.+data EffectiveFieldRule = EffectiveFieldRule+  { presenceClauses :: ![PresenceClause],+    description :: !(Maybe Text),+    allowedValues :: ![Text],+    cardinality :: !Cardinality,+    format :: !(Maybe FieldFormat),+    elementFields :: !(Maybe (Map Text EffectiveFieldRule)),+    objectFields :: !(Maybe (Map Text EffectiveFieldRule)),+    reference :: !(Maybe HandleReferenceRule),+    path :: !(Maybe PathReferenceRule)+  }+  deriving stock (Generic, Eq, Show)++-- | The stable lowercase display name for a cardinality: @any@, @scalar@,+-- @list@, or @object@. These are the names the CLI prints and the names+-- generated profile documentation uses, so a reader who has seen one recognizes+-- the other. @object@ is also the word the CLI already prints for an actual+-- mapping value, so a cardinality-mismatch message reads coherently.+renderCardinalityName :: Cardinality -> Text+renderCardinalityName = \case+  Any -> "any"+  Scalar -> "scalar"+  List -> "list"+  Object -> "object"++-- | The stable display name for a named format: @rfc3339-utc@, @date@, @uri@,+-- @uri-with-scheme(SCHEME)@, @document-handle(PREFIX)@, @actor@,+-- @human-actor@, @integer@, @non-negative-integer@, or @boolean@. As with+-- 'renderCardinalityName', this vocabulary is shared between the CLI and+-- generated documentation and must not drift between them.+renderFieldFormatName :: FieldFormat -> Text+renderFieldFormatName = \case+  Rfc3339Utc -> "rfc3339-utc"+  Date -> "date"+  Uri -> "uri"+  UriWithScheme scheme -> "uri-with-scheme(" <> scheme <> ")"+  DocumentHandle prefix -> "document-handle(" <> prefix <> ")"+  Actor -> "actor"+  HumanActor -> "human-actor"+  Integer -> "integer"+  NonNegativeInteger -> "non-negative-integer"+  Boolean -> "boolean"++-- | The presence clauses that govern whether this key must be present, in the+-- order the profile declared them. An __empty list means the key is optional__:+-- it is fully validated whenever it is present and never reported when absent,+-- in any validation mode. A clause with 'RequiredField' is always checked; a+-- clause with 'RecommendedField' is checked only under+-- 'Okf.Validation.StrictAuthoring'. A clause carrying a 'FieldCondition' applies+-- only when that condition holds for the document being checked.+fieldRulePresenceClauses :: EffectiveFieldRule -> [PresenceClause]+fieldRulePresenceClauses rule = rule ^. #presenceClauses++-- | Prose documenting the key, merged across profile and type scope with+-- type-level prose winning. Purely documentary: it is never checked against a+-- document and can never produce a 'ProfileViolation'.+fieldRuleDescription :: EffectiveFieldRule -> Maybe Text+fieldRuleDescription rule = rule ^. #description++-- | The closed vocabulary of permitted textual values. An __empty list means+-- unconstrained__, not "no value is permitted".+fieldRuleAllowedValues :: EffectiveFieldRule -> [Text]+fieldRuleAllowedValues rule = rule ^. #allowedValues++-- | Whether the key must be a single value, a non-empty list, or either.+fieldRuleCardinality :: EffectiveFieldRule -> Cardinality+fieldRuleCardinality rule = rule ^. #cardinality++-- | The named textual format constraining present values, if any.+fieldRuleFormat :: EffectiveFieldRule -> Maybe FieldFormat+fieldRuleFormat rule = rule ^. #format++-- | The document-reference policy for this key, if any.+fieldRuleReference :: EffectiveFieldRule -> Maybe HandleReferenceRule+fieldRuleReference rule = rule ^. #reference++-- | The path-valued policy for this key, if any. Distinct from+-- 'fieldRuleReference': a handle resolves against the bundle's document-ID+-- index, a path against its concept tree. A rule never carries both — compiling+-- one that does is a 'PathReferenceWithHandleReference' definition error — so a+-- consumer can read whichever is present without disambiguating.+--+-- Unlike 'fieldRuleReference' this can be present on a rule taken from+-- 'fieldRuleElementFields' or 'fieldRuleObjectFields', because+-- @sources[].resource@ is the field the policy exists for.+fieldRulePath :: EffectiveFieldRule -> Maybe PathReferenceRule+fieldRulePath rule = rule ^. #path++-- | Rules for the flat object stored in each element of a list-valued key,+-- keyed by nested key name, or 'Nothing' when the key declares no nested shape.+-- Nested rules are depth-bounded: a nested rule never itself has element fields,+-- so 'fieldRuleElementFields' on a value taken from this map is always+-- 'Nothing'.+fieldRuleElementFields :: EffectiveFieldRule -> Maybe (Map Text EffectiveFieldRule)+fieldRuleElementFields rule = rule ^. #elementFields++-- | Rules for the members of the mapping stored at this key, keyed by member+-- name, or 'Nothing' when the key declares no object shape. Like+-- 'fieldRuleElementFields' this is depth-bounded: a value taken from this map+-- always has 'Nothing' for both nested accessors. A rule may declare both, which+-- means either spelling of the value is accepted and both are checked against+-- the same member rules.+fieldRuleObjectFields :: EffectiveFieldRule -> Maybe (Map Text EffectiveFieldRule)+fieldRuleObjectFields rule = rule ^. #objectFields++-- | Whether this clause demands the key or merely recommends it.+presenceClauseRequirement :: PresenceClause -> FieldRequirement+presenceClauseRequirement clause = clause ^. #requirement++-- | The same-scope predicate gating this clause, or 'Nothing' when it always+-- applies.+presenceClauseCondition :: PresenceClause -> Maybe FieldCondition+presenceClauseCondition clause = clause ^. #condition++-- | A raw profile whose authoring contradictions have been rejected and whose+-- effective profile-plus-type frontmatter rules have been precomputed.+data CompiledProfile = CompiledProfile+  { spec :: !ProfileSpec,+    baseRules :: !(Map Text EffectiveFieldRule),+    rulesByType :: !(Map Text (Map Text EffectiveFieldRule)),+    -- | @requireBundleVersion@ already parsed, so 'validateProfileVersion' never+    -- re-parses and cannot disagree with what compilation accepted.+    requiredBundleVersion :: !(Maybe OkfVersion)+  }+  deriving stock (Generic, Eq, Show)++compiledProfileSpec :: CompiledProfile -> ProfileSpec+compiledProfileSpec compiled = compiled ^. #spec++-- | The minimum OKF version the profile requires its bundle to declare, already+-- parsed. 'Nothing' when the profile requires nothing, which is the default and+-- the case for almost every profile.+compiledProfileRequiredBundleVersion :: CompiledProfile -> Maybe OkfVersion+compiledProfileRequiredBundleVersion compiled = compiled ^. #requiredBundleVersion++-- | The concept @type@ strings the profile declares, in the order the descriptor+-- declares them. Declaration order is the author's and is preserved because+-- documentation and display should follow it rather than an alphabetical+-- reordering.+compiledProfileTypeNames :: CompiledProfile -> [Text]+compiledProfileTypeNames compiled =+  [rule ^. #type_ | rule <- compiledProfileSpec compiled ^. #types]++-- | The rules that apply to every document, whatever its type, keyed by+-- frontmatter key name.+compiledProfileBaseRules :: CompiledProfile -> Map Text EffectiveFieldRule+compiledProfileBaseRules compiled = compiled ^. #baseRules++-- | The rules that apply to a document of the given @type@: the profile-scope+-- rules merged with that type's own. A type the profile does not declare falls+-- back to the profile-scope rules alone, because a profile with+-- @allowUnknownTypes = True@ still applies its profile-wide expectations to a+-- document whose type it does not recognize.+compiledProfileRulesForType :: CompiledProfile -> Text -> Map Text EffectiveFieldRule+compiledProfileRulesForType = effectiveRulesForType++compileProfile :: ProfileSpec -> Either (NonEmpty ProfileDefinitionError) CompiledProfile+compileProfile rawSpec =+  case definitionErrors of+    firstError : remainingErrors -> Left (firstError :| remainingErrors)+    [] ->+      Right+        CompiledProfile+          { spec = rawSpec,+            baseRules,+            rulesByType =+              Map.fromList+                [ (rule ^. #type_, mergeRules baseRules (compileRules (rule ^. #frontmatter)))+                | rule <- rawSpec ^. #types+                ],+            -- Safe here and only here: 'requiredBundleVersionErrors' is one of+            -- the checks 'definitionErrors' collects, so reaching this branch+            -- means the value parsed.+            requiredBundleVersion = rawSpec ^. #requireBundleVersion >>= parseOkfVersion+          }+  where+    baseRules = compileRules (rawSpec ^. #frontmatter)+    typeNames = map (^. #type_) (rawSpec ^. #types)+    definitionErrors =+      List.sortOn definitionErrorKey $+        map DuplicateTypeRule (duplicates typeNames)+          <> scopeErrors Nothing (rawSpec ^. #frontmatter)+          <> concat+            [ scopeErrors (Just (rule ^. #type_)) (rule ^. #frontmatter)+            | rule <- rawSpec ^. #types+            ]+          <> vocabularyErrors+          <> cardinalityErrors+          <> nestedCardinalityErrors+          <> objectCardinalityErrors+          <> formatParameterErrors+          <> conflictingFormatErrors+          <> conditionDefinitionErrors+          <> referenceDefinitionErrors+          <> versionErrors+          <> requiredBundleVersionErrors++    definitionErrorKey = \case+      DuplicateTypeRule ctype -> (1 :: Int, ctype, 0 :: Int, "", 0 :: Int)+      DuplicateFieldRule scope listName key ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, listKey listName, key, 0)+      ConflictingFieldRequirement scope key ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, 2, key, 0)+      UnsatisfiableVocabulary scope key _ _ ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, 3, key, 0)+      ConflictingCardinality scope key _ _ ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, 4, key, 0)+      ElementFieldsRequireList scope path cardinality ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, 4, renderFieldPathKey path, fromEnum (cardinality == Scalar))+      InvalidFormatParameter path fieldFormat parameter ->+        (2, renderFieldPathKey path, 5, Text.pack (show fieldFormat), Text.length parameter)+      ConflictingFieldFormat path profileFormat typeFormat ->+        (2, renderFieldPathKey path, 6, Text.pack (show profileFormat), fromEnum (profileFormat == typeFormat))+      EmptyConditionValues scope target source -> conditionErrorKey scope target source 7+      ConditionFieldNotDeclared scope target source -> conditionErrorKey scope target source 8+      ConditionFieldNotScalar scope target source cardinality ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, 9, renderFieldPathKey target <> ":" <> renderFieldPathKey source, fromEnum (cardinality == Scalar))+      ConditionFieldOpenVocabulary scope target source -> conditionErrorKey scope target source 10+      ConditionFieldHasUnreachableValues scope target source _ _ -> conditionErrorKey scope target source 11+      SelfConditionalField scope target ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, 12, renderFieldPathKey target, 0)+      InvalidReferencePrefix scope target prefix -> referenceErrorKey scope target 13 prefix+      ReferencePrefixNotDeclared scope target prefix -> referenceErrorKey scope target 14 prefix+      ReferenceRequiresIdField scope target -> referenceErrorKey scope target 15 ""+      InvalidExternalReferenceScheme scope target scheme -> referenceErrorKey scope target 16 scheme+      ConflictingReferencePrefix ctype target profilePrefix typePrefix ->+        (1, ctype, 17, renderFieldPathKey target <> ":" <> profilePrefix, Text.length typePrefix)+      ReferenceWithFormat scope target fieldFormat -> referenceErrorKey scope target 18 (Text.pack (show fieldFormat))+      OptionalFieldWithCondition scope target ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, 19, renderFieldPathKey target, 0)+      ObjectFieldsRequireObjectShape scope fieldPath cardinality ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, 20, renderFieldPathKey fieldPath, fromEnum (cardinality == Scalar))+      PathReferenceWithHandleReference scope target -> referenceErrorKey scope target 21 ""+      -- The two version-parse errors are profile-wide rather than scoped, and+      -- rank below every scope rank: if the declared version is unreadable, every+      -- version-derived error below is downstream noise and the reader should see+      -- the cause first. Nothing constrains the first component to be+      -- non-negative.+      InvalidProfileOkfVersion rawVersion -> (-1, rawVersion, 0, "", 0)+      ProfileOkfVersionNotUnderstood rawVersion -> (-1, rawVersion, 1, "", 0)+      InvalidRequiredBundleVersion rawVersion -> (-1, rawVersion, 2, "", 0)+      FieldSupersededInOkfVersion scope path _declared supersededIn ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, 23, renderFieldPathKey path <> ":" <> supersededIn, 0)+      FormatRequiresOkfVersion scope path fieldFormat _declared introducedIn ->+        let (scopeRank, typeName) = scopeKey scope+         in (scopeRank, typeName, 24, renderFieldPathKey path <> ":" <> introducedIn, Text.length (Text.pack (show fieldFormat)))++    scopeKey Nothing = (0, "")+    scopeKey (Just ctype) = (1, ctype)+    listKey "required" = 0+    listKey _ = 1+    conditionErrorKey scope target source rank =+      let (scopeRank, typeName) = scopeKey scope+       in (scopeRank, typeName, rank, renderFieldPathKey target <> ":" <> renderFieldPathKey source, 0)+    referenceErrorKey scope target rank detail =+      let (scopeRank, typeName) = scopeKey scope+       in (scopeRank, typeName, rank, renderFieldPathKey target <> ":" <> detail, 0)++    scopeErrors scope FrontmatterRules {required, recommended, optional} =+      [DuplicateFieldRule scope "required" key | key <- duplicates (map (^. #field) required)]+        <> [DuplicateFieldRule scope "recommended" key | key <- duplicates (map (^. #field) recommended)]+        <> [DuplicateFieldRule scope "optional" key | key <- duplicates (map (^. #field) optional)]+        <> [ ConflictingFieldRequirement scope key+           | key <- presenceListCollisions (map (^. #field) required) (map (^. #field) recommended) (map (^. #field) optional)+           ]+        <> concatMap (nestedScopeErrors scope) (required <> recommended <> optional)++    nestedScopeErrors scope parentRule =+      concatMap oneNestedRuleSet (declaredNestedRuleSets parentRule)+      where+        oneNestedRuleSet NestedRules {required, recommended, optional} =+          let qualify key = parentRule ^. #field <> "." <> key+           in [DuplicateFieldRule scope "nested required" (qualify key) | key <- duplicates (map (^. #field) required)]+                <> [DuplicateFieldRule scope "nested recommended" (qualify key) | key <- duplicates (map (^. #field) recommended)]+                <> [DuplicateFieldRule scope "nested optional" (qualify key) | key <- duplicates (map (^. #field) optional)]+                <> [ ConflictingFieldRequirement scope (qualify key)+                   | key <- presenceListCollisions (map (^. #field) required) (map (^. #field) recommended) (map (^. #field) optional)+                   ]++    -- One key classified by more than one presence list at a single scope. The+    -- profile cannot say both "always check for this" and "never check for+    -- this", so any pairing is a definition error rather than a precedence rule.+    presenceListCollisions requiredKeys recommendedKeys optionalKeys =+      List.nub . List.sort . concat $+        [ List.intersect requiredKeys recommendedKeys,+          List.intersect requiredKeys optionalKeys,+          List.intersect recommendedKeys optionalKeys+        ]++    duplicates = mapMaybe duplicateHead . List.group . List.sort+    duplicateHead (candidate : _ : _) = Just candidate+    duplicateHead _ = Nothing++    vocabularyErrors =+      [ UnsatisfiableVocabulary (Just (rule ^. #type_)) key profileValues typeValues+      | rule <- rawSpec ^. #types,+        let typeRules = compileRules (rule ^. #frontmatter),+        (key, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),+        let profileValues = profileRule ^. #allowedValues+            typeValues = typeRule ^. #allowedValues,+        not (null profileValues),+        not (null typeValues),+        null (mergeVocabulary profileValues typeValues)+      ]+        <> [ UnsatisfiableVocabulary (Just (rule ^. #type_)) (parentKey <> "." <> nestedKey) profileValues typeValues+           | rule <- rawSpec ^. #types,+             let typeRules = compileRules (rule ^. #frontmatter),+             (parentKey, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),+             (profileNested, typeNested) <- pairedNestedRuleMaps profileRule typeRule,+             (nestedKey, (profileNestedRule, typeNestedRule)) <- Map.toAscList (Map.intersectionWith (,) profileNested typeNested),+             let profileValues = profileNestedRule ^. #allowedValues+                 typeValues = typeNestedRule ^. #allowedValues,+             not (null profileValues),+             not (null typeValues),+             null (mergeVocabulary profileValues typeValues)+           ]++    cardinalityErrors =+      [ ConflictingCardinality (Just (rule ^. #type_)) key profileCardinality typeCardinality+      | rule <- rawSpec ^. #types,+        let typeRules = compileRules (rule ^. #frontmatter),+        (key, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),+        let profileCardinality = profileRule ^. #cardinality+            typeCardinality = typeRule ^. #cardinality,+        profileCardinality /= Any,+        typeCardinality /= Any,+        profileCardinality /= typeCardinality+      ]+        <> [ ConflictingCardinality (Just (rule ^. #type_)) (parentKey <> "." <> nestedKey) profileCardinality typeCardinality+           | rule <- rawSpec ^. #types,+             let typeRules = compileRules (rule ^. #frontmatter),+             (parentKey, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),+             (profileNested, typeNested) <- pairedNestedRuleMaps profileRule typeRule,+             (nestedKey, (profileNestedRule, typeNestedRule)) <- Map.toAscList (Map.intersectionWith (,) profileNested typeNested),+             let profileCardinality = profileNestedRule ^. #cardinality+                 typeCardinality = typeNestedRule ^. #cardinality,+             profileCardinality /= Any,+             typeCardinality /= Any,+             profileCardinality /= typeCardinality+           ]++    nestedCardinalityErrors =+      [ ElementFieldsRequireList scope (topLevelFieldPath (fieldRule ^. #field)) Scalar+      | (scope, rules) <- scopedFrontmatterRules,+        fieldRule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional,+        isJust (fieldRule ^. #elementFields),+        fieldRule ^. #cardinality == Scalar+      ]++    -- The mirror image: @objectFields@ says the value is a mapping, and neither+    -- an explicit @scalar@ nor an explicit @list@ can be one.+    objectCardinalityErrors =+      [ ObjectFieldsRequireObjectShape scope (topLevelFieldPath (fieldRule ^. #field)) declared+      | (scope, rules) <- scopedFrontmatterRules,+        fieldRule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional,+        isJust (fieldRule ^. #objectFields),+        let declared = fieldRule ^. #cardinality,+        declared == Scalar || declared == List+      ]++    scopedFrontmatterRules =+      (Nothing, rawSpec ^. #frontmatter)+        : [(Just (rule ^. #type_), rule ^. #frontmatter) | rule <- rawSpec ^. #types]++    -- The nested rule sets one raw rule declares: its list-element rules, its+    -- object-member rules, or both. Deduplicated because @mk.recordOrList@+    -- deliberately declares the same rules under both names, and a definition+    -- error names a path such as @verified.by@ that does not distinguish the two+    -- — so without this the same incoherence would be reported twice.+    declaredNestedRuleSets rawRule =+      List.nub (catMaybes [rawRule ^. #elementFields, rawRule ^. #objectFields])++    -- The same idea across two scopes: the nested maps a profile-scope rule and+    -- a type-scope rule both declare, paired shape with matching shape. Pairing+    -- an element map against an object map would compare rules that never meet.+    pairedNestedRuleMaps profileRule typeRule =+      List.nub+        [ (profileNested, typeNested)+        | nestedMap <- [(^. #elementFields), (^. #objectFields)],+          Just profileNested <- [nestedMap profileRule],+          Just typeNested <- [nestedMap typeRule]+        ]++    formatParameterErrors =+      [ InvalidFormatParameter (topLevelFieldPath (rule ^. #field)) fieldFormat parameter+      | rules <- (rawSpec ^. #frontmatter) : map (^. #frontmatter) (rawSpec ^. #types),+        rule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional,+        Just (fieldFormat, parameter) <- [invalidFormatParameter =<< rule ^. #format]+      ]+        <> [ InvalidFormatParameter (nestedDefinitionPath (rule ^. #field) (nestedRule ^. #field)) fieldFormat parameter+           | rules <- (rawSpec ^. #frontmatter) : map (^. #frontmatter) (rawSpec ^. #types),+             rule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional,+             nestedRules <- declaredNestedRuleSets rule,+             nestedRule <- nestedRules ^. #required <> nestedRules ^. #recommended <> nestedRules ^. #optional,+             Just (fieldFormat, parameter) <- [invalidFormatParameter =<< nestedRule ^. #format]+           ]++    conflictingFormatErrors =+      [ ConflictingFieldFormat (topLevelFieldPath key) profileFormat typeFormat+      | rule <- rawSpec ^. #types,+        let typeRules = compileRules (rule ^. #frontmatter),+        (key, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),+        Just profileFormat <- [profileRule ^. #format],+        Just typeFormat <- [typeRule ^. #format],+        mergeFieldFormat (Just profileFormat) (Just typeFormat) == Nothing+      ]+        <> [ ConflictingFieldFormat (nestedDefinitionPath parentKey nestedKey) profileFormat typeFormat+           | rule <- rawSpec ^. #types,+             let typeRules = compileRules (rule ^. #frontmatter),+             (parentKey, (profileRule, typeRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeRules),+             (profileNested, typeNested) <- pairedNestedRuleMaps profileRule typeRule,+             (nestedKey, (profileNestedRule, typeNestedRule)) <- Map.toAscList (Map.intersectionWith (,) profileNested typeNested),+             Just profileFormat <- [profileNestedRule ^. #format],+             Just typeFormat <- [typeNestedRule ^. #format],+             mergeFieldFormat (Just profileFormat) (Just typeFormat) == Nothing+           ]++    conditionDefinitionErrors =+      conditionErrors Nothing Nothing (rawSpec ^. #frontmatter) baseRules+        <> concat+          [ let typeRules = compileRules (rule ^. #frontmatter)+                mergedRules = mergeRules baseRules typeRules+             in conditionErrors (Just (rule ^. #type_)) Nothing (rule ^. #frontmatter) mergedRules+          | rule <- rawSpec ^. #types+          ]++    conditionErrors scope parent rules effectiveRules =+      concatMap (fieldConditionErrors scope parent effectiveRules) (rules ^. #required <> rules ^. #recommended)+        <> [ deadCondition scope parent (rawRule ^. #field)+           | rawRule <- rules ^. #optional,+             isJust (rawRule ^. #when)+           ]+        <> List.nub+          ( concat+              [ concatMap+                  (fieldConditionErrors scope (Just (rawRule ^. #field)) effectiveNestedRules)+                  (nestedRules ^. #required <> nestedRules ^. #recommended)+                  <> [ deadCondition scope (Just (rawRule ^. #field)) (nestedRule ^. #field)+                     | nestedRule <- nestedRules ^. #optional,+                       isJust (nestedRule ^. #when)+                     ]+              | rawRule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional,+                let effectiveRule = Map.lookup (rawRule ^. #field) effectiveRules,+                (nestedRules, effectiveNestedRules) <-+                  catMaybes+                    [ (,) <$> (rawRule ^. #elementFields) <*> (effectiveRule >>= (^. #elementFields)),+                      (,) <$> (rawRule ^. #objectFields) <*> (effectiveRule >>= (^. #objectFields))+                    ]+              ]+          )++    -- A condition gates presence, and an optional rule has no presence clause to+    -- gate, so the pairing is dead in the descriptor rather than a weaker rule.+    deadCondition scope parent key =+      OptionalFieldWithCondition+        scope+        (maybe (topLevelFieldPath key) (\parentKey -> nestedDefinitionPath parentKey key) parent)++    fieldConditionErrors scope parent effectiveRules rawRule =+      case rawRule ^. #when of+        Nothing -> []+        Just FieldCondition {field = sourceKey, hasValue = conditionValues} ->+          let targetKey = rawRule ^. #field+              targetPath = maybe (topLevelFieldPath targetKey) (\parentKey -> nestedDefinitionPath parentKey targetKey) parent+              sourcePath = maybe (topLevelFieldPath sourceKey) (\parentKey -> nestedDefinitionPath parentKey sourceKey) parent+              normalizedValues = deduplicate conditionValues+              sourceErrors =+                case Map.lookup sourceKey effectiveRules of+                  Nothing -> [ConditionFieldNotDeclared scope targetPath sourcePath]+                  Just sourceRule ->+                    [ ConditionFieldNotScalar scope targetPath sourcePath (sourceRule ^. #cardinality)+                    | sourceRule ^. #cardinality /= Scalar+                    ]+                      <> [ ConditionFieldOpenVocabulary scope targetPath sourcePath+                         | null (sourceRule ^. #allowedValues)+                         ]+                      <> let unreachable = filter (`notElem` sourceRule ^. #allowedValues) normalizedValues+                          in [ ConditionFieldHasUnreachableValues scope targetPath sourcePath unreachable (sourceRule ^. #allowedValues)+                             | not (null (sourceRule ^. #allowedValues)),+                               not (null unreachable)+                             ]+           in [EmptyConditionValues scope targetPath sourcePath | null normalizedValues]+                <> [SelfConditionalField scope targetPath | targetKey == sourceKey]+                <> sourceErrors++    referenceDefinitionErrors =+      List.nub $+        concatMap rawReferenceErrors scopedRules+          <> concatMap mergedReferenceErrors (rawSpec ^. #types)+      where+        declaredPrefixes = mapMaybe (^. #idPrefix) (rawSpec ^. #types)+        scopedRules =+          (Nothing, rawSpec ^. #frontmatter)+            : [(Just (rule ^. #type_), rule ^. #frontmatter) | rule <- rawSpec ^. #types]++        rawReferenceErrors (scope, rules) =+          concatMap (fieldReferenceErrors scope) topLevelRules+            <> concatMap (fieldPathErrors scope) topLevelRules+            -- Path rules are declarable at nested and object scope too, which+            -- is where @sources[].resource@ lives, so the walk descends. It+            -- hangs on 'declaredNestedRuleSets' rather than iterating+            -- @elementFields@ and @objectFields@ separately, because+            -- @mk.recordOrList@ declares one rule set under both names and a+            -- @FieldPath@ such as @sources.resource@ cannot tell them apart.+            <> [ nestedError+               | rule <- topLevelRules,+                 nestedRules <- declaredNestedRuleSets rule,+                 nestedRule <- nestedRules ^. #required <> nestedRules ^. #recommended <> nestedRules ^. #optional,+                 nestedError <-+                   pathPolicyErrors+                     scope+                     (nestedDefinitionPath (rule ^. #field) (nestedRule ^. #field))+                     (nestedRule ^. #format)+                     Nothing+                     (nestedRule ^. #path)+               ]+          where+            topLevelRules = rules ^. #required <> rules ^. #recommended <> rules ^. #optional++        fieldReferenceErrors scope rule =+          case rule ^. #reference of+            Nothing -> []+            Just policy ->+              let path = topLevelFieldPath (rule ^. #field)+                  prefix = policy ^. #localPrefix+                  schemes = deduplicateSchemes (policy ^. #externalUriSchemes)+               in [InvalidReferencePrefix scope path prefix | not (validDocumentHandlePrefix prefix)]+                    <> [ReferencePrefixNotDeclared scope path prefix | prefix `notElem` declaredPrefixes]+                    <> [ReferenceRequiresIdField scope path | isNothing (rawSpec ^. #idField)]+                    <> [InvalidExternalReferenceScheme scope path scheme | scheme <- schemes, not (validUriScheme scheme)]+                    <> [ReferenceWithFormat scope path fieldFormat | Just fieldFormat <- [rule ^. #format]]++        fieldPathErrors scope rule =+          pathPolicyErrors+            scope+            (topLevelFieldPath (rule ^. #field))+            (rule ^. #format)+            (rule ^. #reference)+            (rule ^. #path)++        -- The three ways a path policy can be incoherent on its own. Two reuse+        -- the handle-reference constructors because the claim is identical: a+        -- scheme that is not a legal URI scheme, and a structural interpretation+        -- of a value paired with a textual format that would be checked against+        -- the same text. The third is genuinely new — a value cannot be resolved+        -- as both a @PREFIX-N@ handle and a §6.2 path — and cannot arise at+        -- nested scope, where 'NestedFieldRule' carries no handle policy.+        pathPolicyErrors scope path declaredFormat handlePolicy = \case+          Nothing -> []+          Just policy ->+            [ InvalidExternalReferenceScheme scope path scheme+            | scheme <- deduplicateSchemes (policy ^. #externalUriSchemes),+              not (validUriScheme scheme)+            ]+              <> [ReferenceWithFormat scope path fieldFormat | Just fieldFormat <- [declaredFormat]]+              <> [PathReferenceWithHandleReference scope path | isJust handlePolicy]++        mergedReferenceErrors typeRule =+          [ ConflictingReferencePrefix (typeRule ^. #type_) (topLevelFieldPath key) (profilePolicy ^. #localPrefix) (typePolicy ^. #localPrefix)+          | let typeFields = compileRules (typeRule ^. #frontmatter),+            (key, (profileRule, typeFieldRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeFields),+            Just profilePolicy <- [profileRule ^. #reference],+            Just typePolicy <- [typeFieldRule ^. #reference],+            profilePolicy ^. #localPrefix /= typePolicy ^. #localPrefix+          ]+            <> [ ReferenceWithFormat (Just (typeRule ^. #type_)) (topLevelFieldPath key) fieldFormat+               | let typeFields = compileRules (typeRule ^. #frontmatter),+                 (key, (profileRule, typeFieldRule)) <- Map.toAscList (Map.intersectionWith (,) baseRules typeFields),+                 (referenceRule, formatRule) <- [(profileRule, typeFieldRule), (typeFieldRule, profileRule)],+                 isJust (referenceRule ^. #reference),+                 Just fieldFormat <- [formatRule ^. #format]+               ]++    -- Only a value okf cannot parse is rejected. An unknown /major/ is+    -- deliberately accepted, unlike in @okfVersion@: there the profile is asking+    -- okf to interpret rules it may not understand, while here it is stating a+    -- minimum that a bundle's own declaration is compared against, which stays+    -- meaningful whatever the major is.+    requiredBundleVersionErrors =+      case rawSpec ^. #requireBundleVersion of+        Just rawVersion+          | isNothing (parseOkfVersion rawVersion) -> [InvalidRequiredBundleVersion rawVersion]+        _ -> []++    versionErrors =+      case effectiveProfileVersion (rawSpec ^. #okfVersion) of+        Left versionError -> [versionError]+        Right effectiveVersion ->+          let atLeastV02 = effectiveVersion >= okfVersion02+              v02Text = renderOkfVersion okfVersion02+              -- The /effective/ version, not the raw declared string: a profile+              -- declaring 0.9 is checked as 0.2 and its diagnostics should say so+              -- rather than repeating a number okf did not act on.+              declaredText = renderOkfVersion effectiveVersion+           in -- A key v0.2 superseded, demanded by a profile declaring v0.2 or+              -- later. Deliberately /not/ checked in the optional list: a team+              -- migrating a corpus wants @generated@ required and @timestamp@+              -- tolerated but not demanded, and the optional list says exactly+              -- that. This is the one check whose answer depends on which presence+              -- list a rule came from, so it reads the raw lists rather than the+              -- compiled map, which erases the distinction into presence clauses.+              [ FieldSupersededInOkfVersion scope (topLevelFieldPath (rule ^. #field)) declaredText v02Text+              | atLeastV02,+                (scope, rules) <- scopedFrontmatterRules,+                rule <- rules ^. #required <> rules ^. #recommended,+                rule ^. #field `elem` fieldsSupersededInV02+              ]+                -- The actor formats encode the specification §7 convention that+                -- v0.2 introduced. A format is an okf descriptor feature rather+                -- than a key name, so unlike the mirror case below it has no+                -- house-convention reading: @FieldFormat.Actor@ /is/ §7.+                <> [ FormatRequiresOkfVersion scope path fieldFormat declaredText v02Text+                   | not atLeastV02,+                     (scope, path, fieldFormat) <- scopedFormats,+                     fieldFormat `elem` [Actor, HumanActor]+                   ]++    -- There is deliberately no mirror check, "a profile declaring v0.1 names a+    -- key v0.2 introduced", which is why 'fieldsIntroducedInV02' is unused here.+    -- A profile key /name/ does not imply the OKF core key of that name: per+    -- docs/adr/1-profile-declared-document-ids.md, constraining keys the core+    -- format does not own is what profiles are for, and @status@, @sources@, and+    -- @verified@ are ordinary words teams were already using as house conventions+    -- before v0.2 claimed them. Such a check is both retroactive and ambiguous,+    -- which docs/adr/11-growing-the-profile-descriptor-language.md forbids.++    -- Every declared format paired with the path it sits at, top-level first and+    -- then nested. Only the format checks descend: 'fieldsIntroducedInV02' and+    -- 'fieldsSupersededInV02' name /concept-level/ frontmatter keys, so matching+    -- them against a member of a record would reject a profile whose element+    -- happens to be called @status@ for having a v0.2 key it does not have.+    scopedFormats =+      [ (scope, topLevelFieldPath (rule ^. #field), fieldFormat)+      | (scope, rules) <- scopedFrontmatterRules,+        rule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional,+        Just fieldFormat <- [rule ^. #format]+      ]+        <> List.nub+          [ (scope, nestedDefinitionPath (rule ^. #field) (nestedRule ^. #field), fieldFormat)+          | (scope, rules) <- scopedFrontmatterRules,+            rule <- rules ^. #required <> rules ^. #recommended <> rules ^. #optional,+            nestedRules <- declaredNestedRuleSets rule,+            nestedRule <- nestedRules ^. #required <> nestedRules ^. #recommended <> nestedRules ^. #optional,+            Just fieldFormat <- [nestedRule ^. #format]+          ]++    renderFieldPathKey (FieldPath (firstSegment :| remainingSegments)) =+      Text.intercalate "." (map renderSegment (firstSegment : remainingSegments))+    renderSegment (FieldName name) = name+    renderSegment (ArrayIndex elementIndex) = Text.pack (show elementIndex)++-- | The OKF version that introduced the v0.2 frontmatter families and the actor+-- convention. Written out rather than reusing 'supportedOkfVersion', which+-- happens to equal it today: one is "what okf implements" and the other is "what+-- introduced these keys", and they will diverge at the next minor bump.+okfVersion02 :: OkfVersion+okfVersion02 = OkfVersion {okfVersionMajor = 0, okfVersionMinor = 2}++-- | The OKF version a profile's rules are checked against, or why okf cannot+-- tell.+--+-- A higher /minor/ within a known major is clamped, mirroring+-- 'Okf.Validation.versionGate': specification §12 defines a minor bump as+-- backward-compatible additions, so every rule a v0.3 profile can express is one+-- okf already understands.+--+-- An unknown /major/ is deliberately an error, where the bundle side reads+-- best-effort — this is a considered divergence, not an oversight. §12's+-- best-effort instruction is about bundles, which may come from a third party+-- okf cannot ask. A profile is not a document okf is asked to read; it is an+-- instruction to okf about what to check, written by an author who is present.+-- Silently ignoring an instruction okf cannot interpret is worse than saying so.+-- See @docs\/adr\/10-okf-version-declaration-and-best-effort-reading.md@.+effectiveProfileVersion :: Text -> Either ProfileDefinitionError OkfVersion+effectiveProfileVersion rawVersion =+  case parseOkfVersion rawVersion of+    Nothing -> Left (InvalidProfileOkfVersion rawVersion)+    Just declared+      | okfVersionMajor declared == okfVersionMajor supportedOkfVersion ->+          Right (min declared supportedOkfVersion)+      | otherwise -> Left (ProfileOkfVersionNotUnderstood rawVersion)++compileRules :: FrontmatterRules -> Map Text EffectiveFieldRule+compileRules FrontmatterRules {required, recommended, optional} =+  Map.fromList+    ( [ (rule ^. #field, compileFieldRule RequiredField rule)+      | rule <- required+      ]+        <> [ (rule ^. #field, compileFieldRule RecommendedField rule)+           | rule <- recommended+           ]+        <> [ (rule ^. #field, compileOptionalFieldRule rule)+           | rule <- optional+           ]+    )++-- | Compile a rule the profile documents but never demands. It carries no+-- presence clause, so 'applicablePresenceClause' can never find one to report in+-- either validation mode, while every value check still runs from the+-- present-value branch. This is also the value constraints a required or+-- recommended rule is built from.+compileOptionalFieldRule :: FieldRule -> EffectiveFieldRule+compileOptionalFieldRule rule =+  EffectiveFieldRule+    { presenceClauses = [],+      description = rule ^. #description,+      allowedValues = deduplicate (rule ^. #allowedValues),+      cardinality =+        -- Declaring a nested shape and no explicit cardinality refines what the+        -- value may be, because the shape only makes sense against one. A rule+        -- declaring both shapes stays 'Any', which is what lets either spelling+        -- of the OKF v0.2 @verified@ key satisfy it.+        case (rule ^. #objectFields, rule ^. #elementFields, rule ^. #cardinality) of+          (Just _, Just _, Any) -> Any+          (Just _, Nothing, Any) -> Object+          (Nothing, Just _, Any) -> List+          (_, _, Any) -> refineCardinalityForFormat (rule ^. #format)+          (_, _, declared) -> declared,+      format = rule ^. #format,+      elementFields = compileNestedRules <$> rule ^. #elementFields,+      objectFields = compileNestedRules <$> rule ^. #objectFields,+      reference = compileReferenceRule <$> rule ^. #reference,+      path = compilePathRule <$> rule ^. #path+    }++-- | The cardinality a rule with no declared one takes from its format.+--+-- A non-textual format implies a scalar, and without this the rule would be+-- useless: the 'Any' cardinality routes presence through 'legacyValueIsPresent',+-- which counts only non-empty text and non-empty arrays, so a @usage_count:+-- 5000@ is reported /missing/ before its value is ever examined. Refining here+-- rather than widening 'legacyValueIsPresent' keeps the meaning of every+-- descriptor that already exists — in particular a key whose value is @false@+-- keeps being reported as missing when no rule says otherwise.+--+-- An explicitly declared cardinality always wins, including @list@: a list of+-- integers is a coherent thing to demand, so pairing a numeric format with+-- 'List' is left alone rather than made an error.+refineCardinalityForFormat :: Maybe FieldFormat -> Cardinality+refineCardinalityForFormat = \case+  Just Integer -> Scalar+  Just NonNegativeInteger -> Scalar+  Just Boolean -> Scalar+  _ -> Any++compileFieldRule :: FieldRequirement -> FieldRule -> EffectiveFieldRule+compileFieldRule requirement rule =+  (compileOptionalFieldRule rule)+    { presenceClauses = [PresenceClause requirement (compileCondition <$> rule ^. #when)]+    }++compileNestedRules :: NestedRules -> Map Text EffectiveFieldRule+compileNestedRules NestedRules {required, recommended, optional} =+  Map.fromList+    ( [ (rule ^. #field, compileNestedFieldRule RequiredField rule)+      | rule <- required+      ]+        <> [ (rule ^. #field, compileNestedFieldRule RecommendedField rule)+           | rule <- recommended+           ]+        <> [ (rule ^. #field, compileOptionalNestedFieldRule rule)+           | rule <- optional+           ]+    )++-- | The nested counterpart of 'compileOptionalFieldRule'.+compileOptionalNestedFieldRule :: NestedFieldRule -> EffectiveFieldRule+compileOptionalNestedFieldRule rule =+  EffectiveFieldRule+    { presenceClauses = [],+      description = rule ^. #description,+      allowedValues = deduplicate (rule ^. #allowedValues),+      cardinality =+        case rule ^. #cardinality of+          Any -> refineCardinalityForFormat (rule ^. #format)+          declared -> declared,+      format = rule ^. #format,+      elementFields = Nothing,+      -- Nested rules stay depth-bounded: 'NestedFieldRule' has no object member,+      -- so a profile cannot constrain @sources[0].usage_window.from@.+      objectFields = Nothing,+      -- Still 'Nothing': 'NestedFieldRule' carries no document-handle policy.+      reference = Nothing,+      -- But it does carry a path policy, which is the point of the member —+      -- @sources[].resource@ is only reachable here.+      path = compilePathRule <$> rule ^. #path+    }++compileNestedFieldRule :: FieldRequirement -> NestedFieldRule -> EffectiveFieldRule+compileNestedFieldRule requirement rule =+  (compileOptionalNestedFieldRule rule)+    { presenceClauses = [PresenceClause requirement (compileCondition <$> rule ^. #when)]+    }++mergeRules :: Map Text EffectiveFieldRule -> Map Text EffectiveFieldRule -> Map Text EffectiveFieldRule+mergeRules = Map.unionWith mergeEffectiveFieldRule++mergeEffectiveFieldRule :: EffectiveFieldRule -> EffectiveFieldRule -> EffectiveFieldRule+mergeEffectiveFieldRule profileRule typeRule =+  EffectiveFieldRule+    { presenceClauses = profileRule ^. #presenceClauses <> typeRule ^. #presenceClauses,+      description = typeRule ^. #description <|> profileRule ^. #description,+      allowedValues = mergeVocabulary (profileRule ^. #allowedValues) (typeRule ^. #allowedValues),+      cardinality = mergeCardinality (profileRule ^. #cardinality) (typeRule ^. #cardinality),+      format = fromMaybe (profileRule ^. #format) (mergeFieldFormat (profileRule ^. #format) (typeRule ^. #format)),+      elementFields = mergeNestedRuleMaps (profileRule ^. #elementFields) (typeRule ^. #elementFields),+      objectFields = mergeNestedRuleMaps (profileRule ^. #objectFields) (typeRule ^. #objectFields),+      reference = fromMaybe (profileRule ^. #reference) (mergeReferenceRule (profileRule ^. #reference) (typeRule ^. #reference)),+      path = mergePathRule (profileRule ^. #path) (typeRule ^. #path)+    }++-- | Normalize a declared condition for storage in a 'PresenceClause': the shape+-- is unchanged, but the accepted-value list is deduplicated so that a clause+-- reported in a 'ProfileViolation' does not repeat a value the author wrote+-- twice.+compileCondition :: FieldCondition -> FieldCondition+compileCondition rawCondition =+  FieldCondition+    { field = rawCondition ^. #field,+      hasValue = deduplicate (rawCondition ^. #hasValue)+    }++compileReferenceRule :: HandleReferenceRule -> HandleReferenceRule+compileReferenceRule policy =+  HandleReferenceRule+    { localPrefix = policy ^. #localPrefix,+      externalUriSchemes = map Text.toCaseFold (deduplicateSchemes (policy ^. #externalUriSchemes)),+      allowSelf = policy ^. #allowSelf+    }++compilePathRule :: PathReferenceRule -> PathReferenceRule+compilePathRule policy =+  PathReferenceRule+    { externalUriSchemes = map Text.toCaseFold (deduplicateSchemes (policy ^. #externalUriSchemes)),+      allowSelf = policy ^. #allowSelf+    }++-- | Combine a profile-scope path policy with a type-scope one: intersect the+-- permitted schemes and require both scopes to allow self-reference.+--+-- Unlike 'mergeReferenceRule' this is total and needs no @Maybe@-of-@Maybe@+-- result, because a path policy has no @localPrefix@ — the one thing two+-- handle policies can flatly disagree about. Narrowing to the intersection is+-- the same direction 'mergeVocabulary' takes: a type rule tightens the+-- profile-wide rule and never loosens it.+mergePathRule :: Maybe PathReferenceRule -> Maybe PathReferenceRule -> Maybe PathReferenceRule+mergePathRule Nothing typePolicy = typePolicy+mergePathRule profilePolicy Nothing = profilePolicy+mergePathRule (Just profilePolicy) (Just typePolicy) =+  Just+    PathReferenceRule+      { externalUriSchemes =+          filter+            (`Set.member` Set.fromList (typePolicy ^. #externalUriSchemes))+            (profilePolicy ^. #externalUriSchemes),+        allowSelf = profilePolicy ^. #allowSelf && typePolicy ^. #allowSelf+      }++-- | Merge one scope's map of member rules with another's. Used for both+-- @elementFields@ and @objectFields@; it was named for the former until the+-- latter existed and is a plain union-with-merge either way.+mergeNestedRuleMaps :: Maybe (Map Text EffectiveFieldRule) -> Maybe (Map Text EffectiveFieldRule) -> Maybe (Map Text EffectiveFieldRule)+mergeNestedRuleMaps Nothing typeRules = typeRules+mergeNestedRuleMaps profileRules Nothing = profileRules+mergeNestedRuleMaps (Just profileRules) (Just typeRules) = Just (Map.unionWith mergeEffectiveFieldRule profileRules typeRules)++mergeReferenceRule :: Maybe HandleReferenceRule -> Maybe HandleReferenceRule -> Maybe (Maybe HandleReferenceRule)+mergeReferenceRule Nothing typePolicy = Just typePolicy+mergeReferenceRule profilePolicy Nothing = Just profilePolicy+mergeReferenceRule (Just profilePolicy) (Just typePolicy)+  | profilePolicy ^. #localPrefix == typePolicy ^. #localPrefix =+      Just . Just $+        HandleReferenceRule+          { localPrefix = profilePolicy ^. #localPrefix,+            externalUriSchemes =+              filter+                (`Set.member` Set.fromList (typePolicy ^. #externalUriSchemes))+                (profilePolicy ^. #externalUriSchemes),+            allowSelf = profilePolicy ^. #allowSelf && typePolicy ^. #allowSelf+          }+  | otherwise = Nothing++mergeFieldFormat :: Maybe FieldFormat -> Maybe FieldFormat -> Maybe (Maybe FieldFormat)+mergeFieldFormat Nothing typeFormat = Just typeFormat+mergeFieldFormat profileFormat Nothing = Just profileFormat+mergeFieldFormat (Just Uri) (Just typeFormat@(UriWithScheme _)) = Just (Just typeFormat)+mergeFieldFormat (Just profileFormat@(UriWithScheme _)) (Just Uri) = Just (Just profileFormat)+mergeFieldFormat (Just Actor) (Just HumanActor) = Just (Just HumanActor)+mergeFieldFormat (Just HumanActor) (Just Actor) = Just (Just HumanActor)+mergeFieldFormat (Just Integer) (Just NonNegativeInteger) = Just (Just NonNegativeInteger)+mergeFieldFormat (Just NonNegativeInteger) (Just Integer) = Just (Just NonNegativeInteger)+mergeFieldFormat profileFormat typeFormat+  | profileFormat == typeFormat = Just profileFormat+  | otherwise = Nothing++invalidFormatParameter :: FieldFormat -> Maybe (FieldFormat, Text)+invalidFormatParameter fieldFormat =+  case fieldFormat of+    UriWithScheme scheme+      | not (validUriScheme scheme) -> Just (fieldFormat, scheme)+    DocumentHandle prefix+      | not (validDocumentHandlePrefix prefix) -> Just (fieldFormat, prefix)+    _ -> Nothing++validUriScheme :: Text -> Bool+validUriScheme scheme =+  case Text.uncons scheme of+    Just (firstCharacter, rest) -> isAsciiLetter firstCharacter && Text.all validRest rest+    Nothing -> False+  where+    validRest character =+      isAsciiLetter character+        || ('0' <= character && character <= '9')+        || character `elem` ['+', '.', '-']++validDocumentHandlePrefix :: Text -> Bool+validDocumentHandlePrefix prefix =+  case parseDocumentId (prefix <> "-1") of+    Just documentId -> documentId ^. #prefix == prefix+    Nothing -> False++isAsciiLetter :: Char -> Bool+isAsciiLetter character = isAsciiLower character || isAsciiUpper character++mergeCardinality :: Cardinality -> Cardinality -> Cardinality+mergeCardinality Any typeCardinality = typeCardinality+mergeCardinality profileCardinality Any = profileCardinality+mergeCardinality profileCardinality _typeCardinality = profileCardinality++mergeVocabulary :: [Text] -> [Text] -> [Text]+mergeVocabulary [] typeValues = typeValues+mergeVocabulary profileValues [] = profileValues+mergeVocabulary profileValues typeValues =+  filter (`Set.member` Set.fromList typeValues) profileValues++deduplicate :: [Text] -> [Text]+deduplicate = go Set.empty+  where+    go _ [] = []+    go seen (value : rest)+      | value `Set.member` seen = go seen rest+      | otherwise = value : go (Set.insert value seen) rest++deduplicateSchemes :: [Text] -> [Text]+deduplicateSchemes = go Set.empty+  where+    go _ [] = []+    go seen (scheme : rest)+      | normalized `Set.member` seen = go seen rest+      | otherwise = scheme : go (Set.insert normalized seen) rest+      where+        normalized = Text.toCaseFold scheme++effectiveRulesForType :: CompiledProfile -> Text -> Map Text EffectiveFieldRule+effectiveRulesForType compiled ctype =+  Map.findWithDefault (compiled ^. #baseRules) ctype (compiled ^. #rulesByType)++profileFieldDescriptionForType :: CompiledProfile -> Text -> Text -> Maybe Text+profileFieldDescriptionForType compiled ctype key =+  Map.lookup key (effectiveRulesForType compiled ctype) >>= (^. #description)++-- | A parsed document handle: an ASCII-letter-led alphanumeric prefix and a+-- positive number, rendered as @PREFIX-N@.+data DocumentId = DocumentId+  { prefix :: !Text,+    number :: !Natural+  }+  deriving stock (Generic, Eq, Ord, Show)++-- | Parse a strict document handle. The prefix contains one or more ASCII+-- letters or digits and begins with a letter. It is followed by exactly one+-- hyphen and a positive decimal number with no leading zero. Thus @ADR-7@+-- parses, while @ADR-007@, @ADR-0@, @ADR-@, @-7@, @adr 7@, and+-- @ADR-7-extra@ do not.+parseDocumentId :: Text -> Maybe DocumentId+parseDocumentId raw =+  case Text.splitOn "-" raw of+    [prefixText, numberText]+      | validPrefix prefixText,+        validNumberText numberText ->+          case Text.Read.decimal numberText of+            Right (parsedNumber, remainder)+              | Text.null remainder,+                parsedNumber > 0 ->+                  Just (DocumentId prefixText parsedNumber)+            _ -> Nothing+    _ -> Nothing+  where+    validPrefix value =+      case Text.uncons value of+        Just (firstCharacter, rest) ->+          isAsciiLetter firstCharacter && Text.all isAsciiAlphaNumeric rest+        Nothing -> False+    validNumberText value =+      case Text.uncons value of+        Just (firstCharacter, rest) ->+          firstCharacter >= '1'+            && firstCharacter <= '9'+            && Text.all isAsciiDigit rest+        Nothing -> False+    isAsciiDigit character =+      character >= '0' && character <= '9'+    isAsciiAlphaNumeric character =+      isAsciiLetter character || isAsciiDigit character++-- | Render a document handle as @PREFIX-N@.+renderDocumentId :: DocumentId -> Text+renderDocumentId DocumentId {prefix, number} =+  prefix <> "-" <> Text.pack (show number)++-- | Every well-formed handle under the profile's ID field, paired with the+-- concept carrying it and sorted by prefix, number, then concept ID. Concepts+-- without a well-formed handle are omitted. A profile with no ID field yields+-- an empty list.+documentIdsInBundle :: ProfileSpec -> [Concept] -> [(DocumentId, ConceptId)]+documentIdsInBundle spec concepts =+  case spec ^. #idField of+    Nothing -> []+    Just fieldName ->+      List.sortOn+        (\(documentId, cid) -> (documentId, renderConceptId cid))+        [ (documentId, conceptIdOf concept)+        | concept <- concepts,+          Just (String rawDocumentId) <- [frontmatterLookup fieldName (conceptFrontmatter concept)],+          Just documentId <- [parseDocumentId rawDocumentId]+        ]++-- | Allocate one more than the highest document-ID number already used for the+-- given prefix, or number 1 when the prefix is unused. Gaps are deliberately+-- not filled: reusing a retired number could make an old reference silently+-- point at a different document.+nextDocumentId :: ProfileSpec -> [Concept] -> Text -> DocumentId+nextDocumentId spec concepts requestedPrefix =+  DocumentId+    { prefix = requestedPrefix,+      number = highestNumber + 1+    }+  where+    highestNumber =+      List.foldl'+        max+        0+        [ documentId ^. #number+        | (documentId, _) <- documentIdsInBundle spec concepts,+          documentId ^. #prefix == requestedPrefix+        ]++-- | One structural segment of a frontmatter path. EP-2 produces top-level+-- 'FieldName' paths; later bounded nested validation can append field names and+-- array indexes without encoding paths as ad hoc text.+data FieldPathSegment+  = FieldName Text+  | ArrayIndex Int+  deriving stock (Generic, Eq, Ord, Show)++newtype FieldPath = FieldPath+  { segments :: NonEmpty FieldPathSegment+  }+  deriving stock (Generic, Eq, Ord, Show)++topLevelFieldPath :: Text -> FieldPath+topLevelFieldPath key = FieldPath (FieldName key :| [])++nestedDefinitionPath :: Text -> Text -> FieldPath+nestedDefinitionPath parent child =+  FieldPath (FieldName parent :| [FieldName child])++nestedValuePath :: Text -> Int -> Text -> FieldPath+nestedValuePath parent elementIndex child =+  FieldPath (FieldName parent :| [ArrayIndex elementIndex, FieldName child])++nestedElementPath :: Text -> Int -> FieldPath+nestedElementPath parent elementIndex =+  FieldPath (FieldName parent :| [ArrayIndex elementIndex])++-- | A single deviation from a profile. Advisory by default at the CLI layer.+data ProfileViolation+  = -- | concept's @type@ is not listed in the profile and unknown types are disallowed+    TypeNotInProfile ConceptId Text+  | -- | a required frontmatter key is missing or empty (concept, key, activating condition)+    MissingProfileField ConceptId Text (Maybe FieldCondition)+  | -- | a recommended frontmatter key is missing under strict authoring+    MissingRecommendedProfileField ConceptId Text (Maybe FieldCondition)+  | -- | a required field is missing inside one list element record+    MissingNestedProfileField ConceptId FieldPath (Maybe FieldCondition)+  | -- | a recommended nested field is missing under strict authoring+    MissingRecommendedNestedProfileField ConceptId FieldPath (Maybe FieldCondition)+  | -- | a present value is outside the effective textual vocabulary+    ValueNotInVocabulary ConceptId FieldPath [Text] Value+  | -- | a present value has the wrong scalar/list shape+    CardinalityMismatch ConceptId FieldPath Cardinality Value+  | -- | a present value does not satisfy its named textual format+    ValueFormatMismatch ConceptId FieldPath FieldFormat Value+  | -- | a local reference has the right prefix but no valid owner in this bundle+    DanglingHandleReference ConceptId FieldPath Text+  | -- | a parsed local handle uses a prefix other than the declared target prefix+    ReferenceHandlePrefixMismatch ConceptId FieldPath Text Text+  | -- | a reference value is neither textual local handle nor valid absolute URI+    MalformedDocumentReference ConceptId FieldPath Value+  | -- | an absolute external URI uses a scheme the profile did not permit+    ExternalReferenceSchemeNotAllowed ConceptId FieldPath Text [Text]+  | -- | a local handle, or a bundle path, resolves to the concept carrying it+    SelfDocumentReference ConceptId FieldPath Text+  | -- | a path-valued field's value is not one of the three shapes of §6.2+    MalformedPathReference ConceptId FieldPath Value+  | -- | a relative path climbs above the bundle root+    PathEscapesBundle ConceptId FieldPath Text+  | -- | a bundle path names a concept that does not exist in this bundle+    DanglingPathReference ConceptId FieldPath Text+  | -- | a closed profile does not declare this top-level field+    FieldNotInProfile ConceptId Text+  | -- | a declared list element is not an object record+    NestedElementNotRecord ConceptId FieldPath Value+  | -- | concept's file path does not match the type rule's pattern (concept, type, pattern)+    PathPatternMismatch ConceptId Text Text+  | -- | type rule requires a resource scheme but resource is absent (concept, type, scheme)+    MissingResource ConceptId Text Text+  | -- | resource present but its scheme is wrong (concept, expected scheme, actual resource)+    ResourceSchemeMismatch ConceptId Text Text+  | -- | required @# Schema@ section is absent (concept, type)+    MissingSchemaSection ConceptId Text+  | -- | @# Schema@ table columns do not match (concept, type, expected, actual)+    SchemaColumnsMismatch ConceptId Text [Text] [Text]+  | -- | type rule declares an @idPrefix@ but the concept has no handle (concept, type, prefix)+    MissingDocumentId ConceptId Text Text+  | -- | handle present but malformed for the declared prefix (concept, prefix, actual value)+    MalformedDocumentId ConceptId Text Text+  | -- | the same handle appears on more than one concept (handle, concept, other concept)+    DuplicateDocumentId Text ConceptId ConceptId+  | -- | the profile requires the bundle to declare an OKF version it does not+    -- (required version, what the bundle declared, 'Nothing' when undeclared)+    --+    -- The only violation that belongs to the bundle rather than to a concept, so+    -- a consumer grouping violations by 'ConceptId' has nothing to key it on.+    RequiredBundleVersionUnmet Text (Maybe Text)+  deriving stock (Generic, Eq, Show)++-- | Check every concept against a compiled profile, returning all deviations.+-- Profile-wide rules apply even to unknown types; a matching type rule adds its+-- frontmatter rules and the existing type-specific structural checks.+--+-- Existence is decided against the concepts themselves, so a @path@ rule can+-- tell whether a target names a concept and cannot tell whether it names+-- @references\/attesters\/revenue.py@; such a target is accepted unchecked.+-- Callers holding a real directory should use 'validateProfileWith'.+validateProfile :: ValidationProfile -> CompiledProfile -> [Concept] -> [ProfileViolation]+validateProfile =+  validateProfileWithPresence conceptsOnly bundleInventoryOfConcepts+  where+    -- Narrowed to @.md@ on purpose. A caller with concepts and no directory can+    -- decide a @.md@ target, because a 'Concept' /is/ a non-reserved @.md@+    -- file — but it has never been able to see §6.3's+    -- @references/attesters/revenue.py@, and answering 'TargetAbsent' for it+    -- would turn a question okf cannot ask into a rejection.+    conceptsOnly conceptInventory resolved+      | FilePath.takeExtension resolved /= ".md" = TargetUnknown+      | bundleInventoryMember resolved conceptInventory = TargetPresent+      | otherwise = TargetAbsent++-- | 'validateProfile' with the bundle's full file inventory, so a @path@ rule+-- can decide whether a target that is not a concept exists.+--+-- Specification §6.3's own example of a path target is+-- @references\/attesters\/revenue.py@, which is not a concept and which+-- 'validateProfile' therefore accepts unchecked. A caller that walked a real+-- directory has 'Okf.Bundle.walkBundleInventory' and can do better. See+-- @docs\/adr\/13-the-references-convention-and-non-markdown-files.md@.+--+-- Passing an inventory does not make validation touch the filesystem. The+-- inventory is data read once during the bundle walk, where okf is already doing+-- IO, which is the shape @docs\/adr\/5-compile-profile-rules-before-validation.md@+-- requires and the one the core §6.2 check already uses.+validateProfileWith :: BundleInventory -> ValidationProfile -> CompiledProfile -> [Concept] -> [ProfileViolation]+validateProfileWith inventory =+  validateProfileWithPresence everyFile (const inventory)+  where+    everyFile fullInventory resolved+      | bundleInventoryMember resolved fullInventory = TargetPresent+      | otherwise = TargetAbsent++-- | Check a bundle's specification §12 version declaration against the profile's+-- @requireBundleVersion@ setting. Returns @[]@ when the profile requires nothing,+-- which is the default and the case for almost every profile.+--+-- Deliberately a separate entry point rather than a parameter on+-- 'validateProfile' and 'validateProfileWith'. Those two are public and their+-- signatures are depended on downstream, and this check consults no concepts at+-- all: threading a bundle-scoped question through a concept-walking function+-- would be misleading as well as breaking.+--+-- §12 makes the declaration a MAY, so okf's own validator never asks for one —+-- see @docs\/adr\/10-okf-version-declaration-and-best-effort-reading.md@. This is+-- the house-convention half: nothing is reported unless a profile author wrote+-- the field.+--+-- A declaration okf cannot parse counts as unmet. It cannot be compared, okf+-- already reports it separately as a strict-mode authoring lint, and silently+-- passing it would let a typo satisfy a requirement.+validateProfileVersion :: VersionDeclaration -> CompiledProfile -> [ProfileViolation]+validateProfileVersion declaration compiled =+  case compiledProfileRequiredBundleVersion compiled of+    Nothing -> []+    Just required ->+      let unmet = [RequiredBundleVersionUnmet (renderOkfVersion required) declaredText]+       in case declaration of+            -- A bundle ahead of the house minimum is not a deviation: §12 defines+            -- a minor bump as backward-compatible additions.+            VersionDeclared declared | declared >= required -> []+            VersionDeclared _ -> unmet+            VersionUnparseable _ -> unmet+            VersionUndeclared -> unmet+  where+    declaredText = case declaration of+      VersionDeclared declared -> Just (renderOkfVersion declared)+      VersionUnparseable rawVersion -> Just rawVersion+      VersionUndeclared -> Nothing++-- | The shared body of 'validateProfile' and 'validateProfileWith'.+--+-- The first argument decides what a @path@ rule may conclude about a resolved+-- §6.2 target; the second supplies the inventory it consults, derived from the+-- concepts when the caller has no directory to walk. Keeping one implementation+-- is what stops the two entry points from drifting apart on everything /except/+-- the one question that distinguishes them.+validateProfileWithPresence ::+  (BundleInventory -> FilePath -> PathTargetPresence) ->+  ([Concept] -> BundleInventory) ->+  ValidationProfile ->+  CompiledProfile ->+  [Concept] ->+  [ProfileViolation]+validateProfileWithPresence presenceRule inventoryOf validationProfile compiled concepts =+  concatMap checkConcept sortedConcepts <> checkDuplicateDocumentIds spec sortedConcepts+  where+    spec = compiledProfileSpec compiled+    sortedConcepts = List.sortOn (renderConceptId . conceptIdOf) concepts+    rulesByType = [(rule ^. #type_, rule) | rule <- spec ^. #types]+    validDocumentIdIndex = buildValidDocumentIdIndex spec rulesByType sortedConcepts+    -- What this caller can say about a resolved §6.2 path, built once.+    presenceOf = presenceRule (inventoryOf sortedConcepts)++    checkConcept concept =+      let cid = conceptIdOf concept+          ctype = conceptType concept+          fieldViolations = checkFields cid ctype concept <> checkUnknownFields cid ctype concept+       in case lookup ctype rulesByType of+            Nothing ->+              [TypeNotInProfile cid ctype | not (spec ^. #allowUnknownTypes)] <> fieldViolations+            Just rule ->+              fieldViolations+                <> checkPath cid ctype rule+                <> checkResource cid ctype rule concept+                <> checkSchema cid ctype rule concept+                <> checkDocumentId spec cid ctype rule concept++    checkFields cid ctype concept =+      concatMap checkField (Map.toAscList (effectiveRulesForType compiled ctype))+      where+        checkField (key, rule) =+          case evaluateFieldValue rule (frontmatterLookup key (conceptFrontmatter concept)) of+            FieldAbsent actual ->+              presenceViolations key rule+                <> maybe [] (vocabularyViolations key rule) actual+                <> maybe [] (formatViolations key rule) actual+                <> maybe [] (referenceViolations key rule) actual+                <> maybe [] (pathViolations (topLevelFieldPath key) rule) actual+            FieldPresent actual ->+              vocabularyViolations key rule actual+                <> formatViolations key rule actual+                <> referenceViolations key rule actual+                <> pathViolations (topLevelFieldPath key) rule actual+                <> nestedViolations key rule actual+                <> objectViolations key rule actual+            FieldWrongShape actual -> [CardinalityMismatch cid (topLevelFieldPath key) (rule ^. #cardinality) actual]++        presenceViolations key rule =+          case applicablePresenceClause validationProfile (\sourceKey -> frontmatterLookup sourceKey (conceptFrontmatter concept)) rule of+            Nothing -> []+            Just clause ->+              [ case clause ^. #requirement of+                  RequiredField -> MissingProfileField cid key (clause ^. #condition)+                  RecommendedField -> MissingRecommendedProfileField cid key (clause ^. #condition)+              ]+        vocabularyViolations key rule actual =+          [ ValueNotInVocabulary cid (topLevelFieldPath key) (rule ^. #allowedValues) actual+          | not (null (rule ^. #allowedValues)),+            not (valueMatchesVocabulary (rule ^. #allowedValues) actual)+          ]+        formatViolations key rule actual =+          [ ValueFormatMismatch cid (topLevelFieldPath key) fieldFormat actual+          | Just fieldFormat <- [rule ^. #format],+            not (valueMatchesFormat fieldFormat actual)+          ]+        referenceViolations key rule actual =+          case rule ^. #reference of+            Nothing -> []+            Just policy -> validateReferenceValue validDocumentIdIndex cid (topLevelFieldPath key) policy actual++        -- Takes a 'FieldPath' rather than a key because it is shared by all+        -- three scopes: a top-level key, a member of a list element, and a+        -- member of an object-valued mapping.+        pathViolations fieldPath rule actual =+          case rule ^. #path of+            Nothing -> []+            Just policy -> validatePathValue presenceOf cid fieldPath policy actual++        nestedViolations parentKey parentRule = \case+          Array elementValues+            | Just nestedRules <- parentRule ^. #elementFields ->+                concat+                  [ case elementValue of+                      Aeson.Object members ->+                        concatMap+                          (checkRecordMember (nestedValuePath parentKey elementIndex) members)+                          (Map.toAscList nestedRules)+                      _ -> [NestedElementNotRecord cid (nestedElementPath parentKey elementIndex) elementValue]+                  | (elementIndex, elementValue) <- zip [0 ..] (Vector.toList elementValues)+                  ]+          _ -> []++        -- The mapping spelling of the same idea. The value /is/ the record, so+        -- there is no index in the path: a member is reported as+        -- @generated.by@ rather than @generated[0].by@.+        objectViolations parentKey parentRule = \case+          Aeson.Object members+            | Just objectRules <- parentRule ^. #objectFields ->+                concatMap+                  (checkRecordMember (nestedDefinitionPath parentKey) members)+                  (Map.toAscList objectRules)+          _ -> []++        -- Check one member of one record. Shared by the list-element and+        -- object-value walks, which differ only in how they name the member;+        -- the sibling lookup that resolves a @when@ condition stays scoped to+        -- the record the member lives in either way.+        checkRecordMember buildPath members (key, rule) =+          let path = buildPath key+              actualValue = Aeson.KeyMap.lookup (Aeson.Key.fromText key) members+           in case evaluateFieldValue rule actualValue of+                FieldAbsent actual ->+                  nestedPresenceViolations members path rule+                    <> maybe [] (nestedVocabularyViolations path rule) actual+                    <> maybe [] (nestedFormatViolations path rule) actual+                    <> maybe [] (pathViolations path rule) actual+                FieldPresent actual ->+                  nestedVocabularyViolations path rule actual+                    <> nestedFormatViolations path rule actual+                    <> pathViolations path rule actual+                FieldWrongShape actual -> [CardinalityMismatch cid path (rule ^. #cardinality) actual]++        nestedPresenceViolations objectFields path rule =+          case applicablePresenceClause validationProfile lookupSibling rule of+            Nothing -> []+            Just clause ->+              [ case clause ^. #requirement of+                  RequiredField -> MissingNestedProfileField cid path (clause ^. #condition)+                  RecommendedField -> MissingRecommendedNestedProfileField cid path (clause ^. #condition)+              ]+          where+            lookupSibling sourceKey = Aeson.KeyMap.lookup (Aeson.Key.fromText sourceKey) objectFields+        nestedVocabularyViolations path rule actual =+          [ ValueNotInVocabulary cid path (rule ^. #allowedValues) actual+          | not (null (rule ^. #allowedValues)),+            not (valueMatchesVocabulary (rule ^. #allowedValues) actual)+          ]+        nestedFormatViolations path rule actual =+          [ ValueFormatMismatch cid path fieldFormat actual+          | Just fieldFormat <- [rule ^. #format],+            not (valueMatchesFormat fieldFormat actual)+          ]++    checkUnknownFields cid ctype concept+      | spec ^. #allowUnknownFields = []+      | otherwise =+          [ FieldNotInProfile cid key+          | key <- frontmatterKeys (conceptFrontmatter concept),+            key `Set.notMember` allowedFields ctype+          ]++    allowedFields ctype =+      coreFrontmatterFields+        <> Map.keysSet (effectiveRulesForType compiled ctype)+        <> maybe Set.empty Set.singleton (spec ^. #idField)++-- | Index only handles that are valid owners under the compiled profile's raw+-- type declarations: the concept has a matching type rule, that rule declares+-- the parsed handle's exact prefix, and the profile declares the owning field.+-- Multiple owners are retained so a duplicate target still counts as existing;+-- the existing bundle-wide duplicate diagnostic remains authoritative.+buildValidDocumentIdIndex :: ProfileSpec -> [(Text, TypeRule)] -> [Concept] -> Map DocumentId [ConceptId]+buildValidDocumentIdIndex spec rulesByType concepts =+  case spec ^. #idField of+    Nothing -> Map.empty+    Just fieldName ->+      Map.fromListWith+        (flip (<>))+        [ (documentId, [conceptIdOf concept])+        | concept <- concepts,+          Just typeRule <- [lookup (conceptType concept) rulesByType],+          Just expectedPrefix <- [typeRule ^. #idPrefix],+          Just (String rawDocumentId) <- [frontmatterLookup fieldName (conceptFrontmatter concept)],+          Just documentId <- [parseDocumentId rawDocumentId],+          documentId ^. #prefix == expectedPrefix+        ]++validateReferenceValue :: Map DocumentId [ConceptId] -> ConceptId -> FieldPath -> HandleReferenceRule -> Value -> [ProfileViolation]+validateReferenceValue validOwners sourceConcept path policy = \case+  String rawReference -> validateReferenceText validOwners sourceConcept path policy rawReference+  Array values ->+    concat+      [ case value of+          String rawReference -> validateReferenceText validOwners sourceConcept (appendArrayIndex path elementIndex) policy rawReference+          _ -> [MalformedDocumentReference sourceConcept (appendArrayIndex path elementIndex) value]+      | (elementIndex, value) <- zip [0 ..] (Vector.toList values)+      ]+  actual -> [MalformedDocumentReference sourceConcept path actual]++validateReferenceText :: Map DocumentId [ConceptId] -> ConceptId -> FieldPath -> HandleReferenceRule -> Text -> [ProfileViolation]+validateReferenceText validOwners sourceConcept path policy rawReference =+  case parseDocumentId rawReference of+    Just documentId+      | documentId ^. #prefix /= policy ^. #localPrefix ->+          [ReferenceHandlePrefixMismatch sourceConcept path rawReference (policy ^. #localPrefix)]+      | otherwise ->+          case Map.lookup documentId validOwners of+            Nothing -> [DanglingHandleReference sourceConcept path rawReference]+            Just owners+              | not (policy ^. #allowSelf),+                sourceConcept `elem` owners ->+                  [SelfDocumentReference sourceConcept path rawReference]+              | otherwise -> []+    Nothing ->+      case parseURI (Text.unpack rawReference) of+        Just parsed+          | not (Text.null normalizedScheme), normalizedScheme `elem` policy ^. #externalUriSchemes -> []+          | not (Text.null normalizedScheme) ->+              [ ExternalReferenceSchemeNotAllowed+                  sourceConcept+                  path+                  normalizedScheme+                  (policy ^. #externalUriSchemes)+              ]+          | otherwise -> [MalformedDocumentReference sourceConcept path (String rawReference)]+          where+            normalizedScheme = Text.toCaseFold (Text.dropWhileEnd (== ':') (Text.pack (uriScheme parsed)))+        Nothing -> [MalformedDocumentReference sourceConcept path (String rawReference)]++-- | Check one path-valued frontmatter value, at any scope. A list is checked+-- element-wise so that a diagnostic names @sources[1].resource@ rather than the+-- whole list.+validatePathValue :: (FilePath -> PathTargetPresence) -> ConceptId -> FieldPath -> PathReferenceRule -> Value -> [ProfileViolation]+validatePathValue presenceOf sourceConcept path policy = \case+  String rawPath -> validatePathText presenceOf sourceConcept path policy rawPath+  Array values ->+    concat+      [ case value of+          String rawPath ->+            validatePathText presenceOf sourceConcept (appendArrayIndex path elementIndex) policy rawPath+          _ -> [MalformedPathReference sourceConcept (appendArrayIndex path elementIndex) value]+      | (elementIndex, value) <- zip [0 ..] (Vector.toList values)+      ]+  actual -> [MalformedPathReference sourceConcept path actual]++-- | What a caller can say about a resolved §6.2 bundle path.+--+-- Three answers rather than two, because "I cannot tell" is a real state and+-- collapsing it into "absent" turns silence into a rejection. 'validateProfile'+-- is handed concepts alone, so it genuinely cannot say whether §6.3's+-- @references\/attesters\/revenue.py@ is there, and reporting it as dangling+-- would be a claim okf did not check.+data PathTargetPresence+  = -- | The bundle holds it.+    TargetPresent+  | -- | The bundle does not hold it, and the caller can see enough to be sure.+    TargetAbsent+  | -- | The caller cannot answer for this path.+    TargetUnknown+  deriving stock (Generic, Eq, Show)++-- | Check one path value against the §6.2 grammar and the profile's policy.+--+-- Every diagnostic carries the raw text the author wrote rather than the+-- collapsed path okf computed from it, so the message names something findable+-- in the file.+--+-- Existence is decided by the supplied lookup, which reports what the caller can+-- actually see: 'validateProfileWith' holds a real directory's inventory and so+-- resolves §6.3's own @references\/attesters\/revenue.py@, while+-- 'validateProfile' holds the concepts alone and answers 'TargetUnknown' for it.+--+-- The @.md@ branch still goes through 'conceptIdFromFilePath', because that is+-- what decides self-reference and what makes 'MalformedPathReference' reachable+-- for a path no concept ID could be built from. What it no longer decides is+-- whether the target is there.+validatePathText :: (FilePath -> PathTargetPresence) -> ConceptId -> FieldPath -> PathReferenceRule -> Text -> [ProfileViolation]+validatePathText presenceOf sourceConcept path policy rawPath =+  case classifyPathReference sourceConcept rawPath of+    ExternalUrl scheme+      | scheme `elem` policy ^. #externalUriSchemes -> []+      | otherwise ->+          [ExternalReferenceSchemeNotAllowed sourceConcept path scheme (policy ^. #externalUriSchemes)]+    EscapesBundle -> [PathEscapesBundle sourceConcept path rawPath]+    MalformedPath -> [MalformedPathReference sourceConcept path (String rawPath)]+    BundlePath resolved+      | FilePath.takeExtension resolved == ".md" ->+          case conceptIdFromFilePath resolved of+            Left _ -> [MalformedPathReference sourceConcept path (String rawPath)]+            Right target+              | target == sourceConcept,+                not (policy ^. #allowSelf) ->+                  [SelfDocumentReference sourceConcept path rawPath]+              | otherwise -> danglingWhenAbsent resolved+      | otherwise -> danglingWhenAbsent resolved+  where+    danglingWhenAbsent resolved = case presenceOf resolved of+      TargetAbsent -> [DanglingPathReference sourceConcept path rawPath]+      TargetPresent -> []+      TargetUnknown -> []++appendArrayIndex :: FieldPath -> Int -> FieldPath+appendArrayIndex (FieldPath pathSegments) elementIndex =+  FieldPath (pathSegments <> (ArrayIndex elementIndex :| []))++applicablePresenceClause :: ValidationProfile -> (Text -> Maybe Value) -> EffectiveFieldRule -> Maybe PresenceClause+applicablePresenceClause validationProfile lookupValue rule =+  List.find applies requiredClauses+    <|> if validationProfile == StrictAuthoring then List.find applies recommendedClauses else Nothing+  where+    requiredClauses = filter ((== RequiredField) . (^. #requirement)) (rule ^. #presenceClauses)+    recommendedClauses = filter ((== RecommendedField) . (^. #requirement)) (rule ^. #presenceClauses)+    applies clause = maybe True conditionApplies (clause ^. #condition)+    conditionApplies condition =+      case lookupValue (condition ^. #field) of+        Just (String actual) -> actual `elem` condition ^. #hasValue+        _ -> False++valueMatchesVocabulary :: [Text] -> Value -> Bool+valueMatchesVocabulary allowed = \case+  String value -> value `elem` allowed+  Array values -> all elementMatches (Vector.toList values)+  _ -> False+  where+    elementMatches (String value) = value `elem` allowed+    elementMatches _ = False++-- | Whether a present value satisfies a format. Each format declares which+-- value shapes it can match at all: the textual formats match a string, the+-- numeric ones a YAML number, and 'Boolean' a YAML boolean. A list is matched+-- by recursing, so a list of integers satisfies an @integer@ format for the+-- same reason a list of timestamps satisfies @rfc3339-utc@ — a format+-- constrains a value, and a list is a list of values.+valueMatchesFormat :: FieldFormat -> Value -> Bool+valueMatchesFormat fieldFormat actual =+  case actual of+    String value -> textMatchesFormat fieldFormat value+    Array values -> all (valueMatchesFormat fieldFormat) (Vector.toList values)+    Number _ -> numberMatchesFormat fieldFormat actual+    Bool _ -> fieldFormat == Boolean+    _ -> False++textMatchesFormat :: FieldFormat -> Text -> Bool+textMatchesFormat fieldFormat value =+  case fieldFormat of+    Rfc3339Utc ->+      hasExtendedUtcShape value+        && isJust (iso8601ParseM (Text.unpack value) :: Maybe UTCTime)+    Date ->+      hasExtendedDateShape value+        && isJust (iso8601ParseM (Text.unpack value) :: Maybe Day)+    Uri -> isJust (parseURI (Text.unpack value))+    UriWithScheme expectedScheme ->+      case parseURI (Text.unpack value) of+        Just parsed ->+          Text.toCaseFold (Text.dropWhileEnd (== ':') (Text.pack (uriScheme parsed)))+            == Text.toCaseFold expectedScheme+        Nothing -> False+    DocumentHandle expectedPrefix ->+      case parseDocumentId value of+        Just documentId -> documentId ^. #prefix == expectedPrefix+        Nothing -> False+    -- Specification §7 defines exactly three actor shapes, and+    -- 'Actor.parseActor' classifies them, so the format is a case match on its+    -- result rather than a second parser. A value the convention does not+    -- define — the specification's own illustrative @team:ga4-docs@ among them —+    -- is 'Actor.UnclassifiedActor' and is reported.+    Actor ->+      case Actor.parseActor value of+        Actor.UnclassifiedActor _ -> False+        _ -> True+    HumanActor -> Actor.isHumanActor (Actor.parseActor value)+    -- A numeric or boolean format never matches text. A @usage_count: "5000"@+    -- is a quoted string in YAML and is reported rather than coerced, which is+    -- the whole point of being able to declare the format.+    Integer -> False+    NonNegativeInteger -> False+    Boolean -> False++-- | Whether a YAML number satisfies a numeric format. Uses aeson's own+-- 'Integer' decoder, which already rejects a non-integral number, rather than+-- reaching for @scientific@: that package is a dependency of @aeson@ but not of+-- @okf-core@, so it is importable in a scratch experiment and not from here.+-- 'Okf.Document.objectInteger' takes the same route.+numberMatchesFormat :: FieldFormat -> Value -> Bool+numberMatchesFormat fieldFormat actual =+  case Aeson.fromJSON actual :: Aeson.Result Integer of+    Aeson.Error _ -> False+    Aeson.Success parsed ->+      case fieldFormat of+        Integer -> True+        NonNegativeInteger -> parsed >= 0+        _ -> False++hasExtendedDateShape :: Text -> Bool+hasExtendedDateShape value =+  Text.length value == 10+    && Text.index value 4 == '-'+    && Text.index value 7 == '-'++hasExtendedUtcShape :: Text -> Bool+hasExtendedUtcShape value =+  Text.length value >= 20+    && Text.index value 4 == '-'+    && Text.index value 7 == '-'+    && Text.index value 10 == 'T'+    && Text.index value 13 == ':'+    && Text.index value 16 == ':'+    && Text.last value == 'Z'++data FieldValueEvaluation+  = FieldAbsent (Maybe Value)+  | FieldPresent Value+  | FieldWrongShape Value++-- | Decide whether a frontmatter value counts as present for one rule. Takes the+-- whole rule rather than just its cardinality because the 'Any' case has to know+-- whether the rule declares object members: a rule accepting both spellings of+-- the OKF v0.2 @verified@ key stays at 'Any' cardinality and must still count a+-- mapping as present.+--+-- This is the single point at which okf decides presence, so a change here+-- affects every profile check.+evaluateFieldValue :: EffectiveFieldRule -> Maybe Value -> FieldValueEvaluation+evaluateFieldValue _ Nothing = FieldAbsent Nothing+evaluateFieldValue rule (Just actual) =+  case rule ^. #cardinality of+    Any+      | legacyValueIsPresent actual -> FieldPresent actual+      -- A rule that also accepts a mapping counts a non-empty one as present.+      -- Without this a profile declaring both shapes would report `verified`+      -- missing on a document that writes it as a bare mapping.+      | isJust (rule ^. #objectFields), nonEmptyObject actual -> FieldPresent actual+      | otherwise -> FieldAbsent (Just actual)+    Scalar ->+      case actual of+        String value+          | Text.null (Text.strip value) -> FieldAbsent (Just actual)+          | otherwise -> FieldPresent actual+        Number _ -> FieldPresent actual+        Bool _ -> FieldPresent actual+        _ -> FieldWrongShape actual+    List ->+      case actual of+        Array values+          | null values -> FieldAbsent (Just actual)+          | otherwise -> FieldPresent actual+        _ -> FieldWrongShape actual+    Object+      -- An empty mapping is treated as absent for the same reason an empty list+      -- is: a key written with no content is the author saying nothing, and+      -- reporting it missing is more useful than reporting it present and empty.+      | nonEmptyObject actual -> FieldPresent actual+      | isObject actual -> FieldAbsent (Just actual)+      | otherwise -> FieldWrongShape actual++isObject :: Value -> Bool+isObject = \case+  Aeson.Object _ -> True+  _ -> False++nonEmptyObject :: Value -> Bool+nonEmptyObject = \case+  Aeson.Object members -> not (Aeson.KeyMap.null members)+  _ -> False++legacyValueIsPresent :: Value -> Bool+legacyValueIsPresent = \case+  String value -> not (Text.null (Text.strip value))+  Array values -> not (null values)+  _ -> False++-- | Check a profile-declared document ID for one concept.+checkDocumentId :: ProfileSpec -> ConceptId -> Text -> TypeRule -> Concept -> [ProfileViolation]+checkDocumentId spec cid ctype rule concept =+  case (spec ^. #idField, rule ^. #idPrefix) of+    (Just fieldName, Just expectedPrefix) ->+      case frontmatterLookup fieldName (conceptFrontmatter concept) of+        Just (String value)+          | not (Text.null (Text.strip value)) ->+              case parseDocumentId value of+                Just documentId+                  | documentId ^. #prefix == expectedPrefix -> []+                _ -> [MalformedDocumentId cid expectedPrefix value]+        _ -> [MissingDocumentId cid ctype expectedPrefix]+    _ -> []++-- | Check every non-empty value under the profile's ID field for bundle-wide+-- uniqueness. Concept IDs are sorted before grouping so output is deterministic.+checkDuplicateDocumentIds :: ProfileSpec -> [Concept] -> [ProfileViolation]+checkDuplicateDocumentIds spec concepts =+  case spec ^. #idField of+    Nothing -> []+    Just fieldName ->+      concatMap duplicateViolations (groupedHandles fieldName)+  where+    groupedHandles fieldName =+      List.groupBy+        (\(leftHandle, _) (rightHandle, _) -> leftHandle == rightHandle)+        (handles fieldName)+    handles fieldName =+      List.sortOn+        (\(handle, cid) -> (handle, renderConceptId cid))+        [ (handle, conceptIdOf concept)+        | concept <- concepts,+          Just (String handle) <- [frontmatterLookup fieldName (conceptFrontmatter concept)],+          not (Text.null (Text.strip handle))+        ]+    duplicateViolations ((handle, firstConcept) : duplicates) =+      [ DuplicateDocumentId handle firstConcept duplicateConcept+      | (_, duplicateConcept) <- duplicates+      ]+    duplicateViolations [] = []++-- | Project a concept's frontmatter (the document's @frontmatter@ field).+conceptFrontmatter :: Concept -> Frontmatter+conceptFrontmatter concept = conceptDocument concept ^. #frontmatter++-- | A type rule's @pathPattern@, when present, constrains where the concept's+-- file may live.+checkPath :: ConceptId -> Text -> TypeRule -> [ProfileViolation]+checkPath cid ctype rule =+  case rule ^. #pathPattern of+    Nothing -> []+    Just patternText+      | matchPathPattern patternText cid -> []+      | otherwise -> [PathPatternMismatch cid ctype patternText]++-- | Match a concept ID against a segment-glob pattern. @*@ matches exactly one+-- segment; a single trailing @**@ matches one or more remaining segments; every+-- other segment matches literally. Both segment lists must be consumed exactly,+-- except for the trailing @**@ case.+matchPathPattern :: Text -> ConceptId -> Bool+matchPathPattern patternText cid =+  go (Text.splitOn "/" patternText) (Text.splitOn "/" (renderConceptId cid))+  where+    go [] [] = True+    go ["**"] (_ : _) = True+    go ("*" : ps) (_ : ss) = go ps ss+    go (p : ps) (s : ss) = p == s && go ps ss+    go _ _ = False++-- | A type rule's @resourceScheme@, when present, requires a @resource:@ value+-- whose scheme matches.+checkResource :: ConceptId -> Text -> TypeRule -> Concept -> [ProfileViolation]+checkResource cid ctype rule concept =+  case rule ^. #resourceScheme of+    Nothing -> []+    Just scheme ->+      case conceptResource concept of+        Nothing -> [MissingResource cid ctype scheme]+        Just value+          | (scheme <> "://") `Text.isPrefixOf` value -> []+          | otherwise -> [ResourceSchemeMismatch cid scheme value]++-- | A type rule's @# Schema@ contract: when @requireSchemaSection@ is set, the+-- body must contain a @# Schema@ section whose table header begins with the+-- required @schemaColumns@ (case-insensitive, trimmed, compared as a prefix so a+-- team may add trailing columns without tripping the check).+checkSchema :: ConceptId -> Text -> TypeRule -> Concept -> [ProfileViolation]+checkSchema cid ctype rule concept+  | not (rule ^. #requireSchemaSection) = []+  | otherwise =+      case schemaSectionColumns (conceptDocument concept ^. #body) of+        Nothing -> [MissingSchemaSection cid ctype]+        Just actual ->+          let expected = rule ^. #schemaColumns+              norm = map (Text.toLower . Text.strip)+           in [ SchemaColumnsMismatch cid ctype expected actual+              | not (norm expected `List.isPrefixOf` norm actual)+              ]++-- | The header-row columns of the first GitHub-flavored table that follows the+-- first top-level @# Schema@ heading, or 'Nothing' if there is no Schema heading+-- or no following table. Columns are trimmed.+schemaSectionColumns :: Text -> Maybe [Text]+schemaSectionColumns markdown =+  let CMarkGFM.Node _ _ topLevel = CMarkGFM.commonmarkToNode markdownOptions [CMarkGFM.extTable] markdown    in firstTableAfterSchema topLevel  firstTableAfterSchema :: [CMarkGFM.Node] -> Maybe [Text]