@pagefront/lint-commerce 0.9.0 → 0.10.0

package/dist/organization-catalogue.js

@@ -1,4 +1,7 @@
+import { KNOWN_RELEASES } from "./releases.js";
 import { orgE001 } from "./rules/org-e-001.js";
+import { orgE002 } from "./rules/org-e-002.js";
+import { orgE003 } from "./rules/org-e-003.js";
 import { orgW001 } from "./rules/org-w-001.js";
 import { orgW002 } from "./rules/org-w-002.js";
 import { orgW003 } from "./rules/org-w-003.js";
@@ -16,7 +19,7 @@ import { orgW006 } from "./rules/org-w-006.js";
  */
 export const organizationCatalogue = {
     vertical: "commerce",
-    formatVersion: "0.9",
-    catalogueVersion: "0.14.0",
-    rules: [orgE001, orgW001, orgW002, orgW003, orgW004, orgW005, orgW006],
+    releases: KNOWN_RELEASES,
+    catalogueVersion: "0.15.0",
+    rules: [orgE001, orgE002, orgE003, orgW001, orgW002, orgW003, orgW004, orgW005, orgW006],
 };

package/dist/organization-schema.d.ts

@@ -1,6 +1,7 @@
 /**
  * The Pagefront Commerce Organization Sheet JSON Schema
- * (commerce/spec/organization.json, format 0.9), bundled verbatim so
+ * (commerce/spec/organization.json, the current sheet-spec version on
+ * the release line), bundled verbatim so
  * the published package can run Layer 1 validation without the
  * monorepo checkout. Generated from the spec file; the schema drift
  * test (test/schema.test.mjs) fails when the two diverge. Regenerate

package/dist/organization-schema.js

@@ -1,6 +1,7 @@
 /**
  * The Pagefront Commerce Organization Sheet JSON Schema
- * (commerce/spec/organization.json, format 0.9), bundled verbatim so
+ * (commerce/spec/organization.json, the current sheet-spec version on
+ * the release line), bundled verbatim so
  * the published package can run Layer 1 validation without the
  * monorepo checkout. Generated from the spec file; the schema drift
  * test (test/schema.test.mjs) fails when the two diverge. Regenerate
@@ -8,12 +9,12 @@
  */
 export const ORGANIZATION_SCHEMA = {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://themachineweb.org/pagefront/spec/commerce/organization/v0.9.json",
-    "title": "Pagefront Commerce Organization Sheet v0.9",
-    "description": "Formal schema for the Pagefront Commerce Organization Sheet — the sheet describing the entity behind products (brand owner, manufacturer, seller), introduced with commerce format 0.9 alongside the reference-capable legalEntity and the seller-sheet return/shipping model. The data block roots on Schema.org Organization (recognized subtypes permitted; @type is not constrained to a single value). pagefront:commerceRole is the required role discriminator, an array of one or more values from the closed enum brand_owner / manufacturer / seller. pagefront:fulfillmentTerms carries the store-wide shipping defaults as an array of Schema.org-native OfferShippingDetails objects; only the attachment shell is validated, the payload is Schema.org content. pagefront:socialAccount carries the organization's official social accounts (platform / url / handle; publisher-stated only), distinct from sameAs, which carries identity authority records only. pagefront:authorizedResellers carries the brand's authorization claim over its distribution — a pagefront:AuthorizedResellers object with an optional exhaustive flag and a reseller array whose entries name an Organization either as a reference stub (@id) or inline (name plus url and/or address), with optional Schema.org-native areaServed; valid only where commerceRole includes brand_owner (linter ORG-W-006). There is no GTIN-equivalent identifier requirement: identity is @id + name. Validates the envelope and pagefront-namespaced extensions strictly; Schema.org-typed blocks permit additional unspecified properties.",
+    "$id": "https://themachineweb.org/pagefront/spec/commerce/organization/v0.3.0.json",
+    "title": "Pagefront Commerce Organization Sheet 0.3.0",
+    "description": "Sheet spec version 0.3.0, a member of commerce release 0.3.0: the envelope carries release in place of format_version, and $schema names this sheet-spec version; a sheet carrying format_version belongs to the legacy draft line and validates against the legacy schema at .../organization/v0.9.json, which is otherwise identical. Formal schema for the Pagefront Commerce Organization Sheet — the sheet describing the entity behind products (brand owner, manufacturer, seller), introduced with commerce format 0.9 alongside the reference-capable legalEntity and the seller-sheet return/shipping model. The data block roots on Schema.org Organization (recognized subtypes permitted; @type is not constrained to a single value). pagefront:commerceRole is the required role discriminator, an array of one or more values from the closed enum brand_owner / manufacturer / seller. pagefront:fulfillmentTerms carries the store-wide shipping defaults as an array of Schema.org-native OfferShippingDetails objects; only the attachment shell is validated, the payload is Schema.org content. pagefront:socialAccount carries the organization's official social accounts (platform / url / handle; publisher-stated only), distinct from sameAs, which carries identity authority records only. pagefront:authorizedResellers carries the brand's authorization claim over its distribution — a pagefront:AuthorizedResellers object with an optional exhaustive flag and a reseller array whose entries name an Organization either as a reference stub (@id) or inline (name plus url and/or address), with optional Schema.org-native areaServed; valid only where commerceRole includes brand_owner (linter ORG-W-006). There is no GTIN-equivalent identifier requirement: identity is @id + name. Validates the envelope and pagefront-namespaced extensions strictly; Schema.org-typed blocks permit additional unspecified properties.",
     "type": "object",
     "required": [
-        "format_version",
+        "release",
         "schema_org_version",
         "canonical_url",
         "sheet_url",
@@ -25,8 +26,9 @@ export const ORGANIZATION_SCHEMA = {
             "type": "string",
             "format": "uri"
         },
-        "format_version": {
-            "const": "0.9"
+        "release": {
+            "type": "string",
+            "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$"
         },
         "schema_org_version": {
             "type": "string",

package/dist/product-schema.d.ts

@@ -1,6 +1,6 @@
 /**
- * The Pagefront product JSON Schema (commerce/spec/product.json,
- * format 0.9), bundled verbatim so the published package can run
+ * The Pagefront Product Sheet JSON Schema (commerce/spec/product.json,
+ * the current sheet-spec version on the release line), bundled verbatim so the published package can run
  * Layer 1 validation without the monorepo checkout. Generated from
  * the spec file; the schema drift test (test/schema.test.mjs) fails
  * when the two diverge. Regenerate on any schema change, in the same

package/dist/product-schema.js

@@ -1,6 +1,6 @@
 /**
- * The Pagefront product JSON Schema (commerce/spec/product.json,
- * format 0.9), bundled verbatim so the published package can run
+ * The Pagefront Product Sheet JSON Schema (commerce/spec/product.json,
+ * the current sheet-spec version on the release line), bundled verbatim so the published package can run
  * Layer 1 validation without the monorepo checkout. Generated from
  * the spec file; the schema drift test (test/schema.test.mjs) fails
  * when the two diverge. Regenerate on any schema change, in the same
@@ -8,12 +8,12 @@
  */
 export const PRODUCT_SCHEMA = {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://themachineweb.org/pagefront/spec/commerce/product/v0.9.json",
-    "title": "Pagefront Product Sheet v0.9",
-    "description": "Formal schema for the Pagefront product sheet. Revision of 2026-10-01 (breaking, within v0.9): configurator pricing moves from pagefront:configurator to the offer. The configurator loses basePrice, basePriceCurrency and priceFormula, its options lose priceModifier and currency, and it gains an optional @id and an exclusions[] array; configurator dimensions gain affectsPrice, inputType (select or text, for free-text dimensions) and maxLength; Offer and AggregateOffer accept pagefront:configuratorPricing, which names the configurator it prices and carries baseConfiguration, basePrice, modifiers, optional adjustments[] and a pricing completeness flag; every amount field (Offer price, AggregateOffer lowPrice and highPrice, variant price hints, promotion discountAmount, and the pricing block's basePrice, modifiers and adjustment amounts) references a shared definition, a JSON number or a plain decimal string: nonNegativeAmount for prices, bounds, base prices, price hints and discount amounts, and the signed amount for modifiers and adjustment amounts. v0.9 sheets that carried prices inside the configurator no longer validate. v0.9 was otherwise an additive release on top of v0.8: the legalEntity entry's organization now also validates in reference-stub form (@type + @id, no name) so entries can reference a Commerce Organization Sheet; the inline form and all other constraints are unchanged, and v0.8 sheets remain valid once their format_version is updated. v0.8 is an additive release on top of v0.7: it adds a pagefront:featureGroup[] array for grouped, ordered technical specifications (groups of Schema.org PropertyValue entries, with an optional pagefront:presentationValue display variant per entry), a pagefront:productHighlights[] array of ordered publisher-authored selling-point strings, and a pagefront:legalEntity[] array for role-typed legal entities behind a product (closed role enum: brand_owner, licensee, authorized_representative, importer, manufacturer — EU GPSR responsible persons and similar). gtin and gtin13 now accept a string or an array of strings (regional packaging, re-releases); category now accepts the display string, a Schema.org CategoryCode object, or a mixed array of both. The pagefront:Document role enum gains repairability_index, recall_notice, and declaration_of_conformity; the pagefront:RelatedProduct relationship enum gains service. v0.8 also adds two GPSR-driven safety fields: a pagefront:safetyWarning[] array for typed, language-scoped safety warnings (text required; optional pictogram URL and open-vocabulary hazardCategory) and a pagefront:safetyNotice[] array for structured recall/safety notices (closed noticeType enum: recall, warning; closed remedy enum: repair, replacement, refund). v0.7 sheets remain valid under v0.8 once their format_version is updated. Validates the envelope and pagefront-namespaced extensions strictly; Schema.org-typed blocks permit additional unspecified properties.",
+    "$id": "https://themachineweb.org/pagefront/spec/commerce/product/v0.9.0.json",
+    "title": "Pagefront Product Sheet 0.9.0",
+    "description": "Formal schema for the Pagefront Product Sheet, sheet spec version 0.9.0, a member of commerce release 0.3.0. The envelope carries release in place of format_version: release names the commerce release the sheet is written against, and $schema names this sheet-spec version. A sheet carrying format_version belongs to the legacy draft line and validates against the legacy schema at .../product/v0.9.json, which is otherwise identical. History, in legacy format versions: revision of 2026-10-01 (breaking, within v0.9): configurator pricing moves from pagefront:configurator to the offer. The configurator loses basePrice, basePriceCurrency and priceFormula, its options lose priceModifier and currency, and it gains an optional @id and an exclusions[] array; configurator dimensions gain affectsPrice, inputType (select or text, for free-text dimensions) and maxLength; Offer and AggregateOffer accept pagefront:configuratorPricing, which names the configurator it prices and carries baseConfiguration, basePrice, modifiers, optional adjustments[] and a pricing completeness flag; every amount field (Offer price, AggregateOffer lowPrice and highPrice, variant price hints, promotion discountAmount, and the pricing block's basePrice, modifiers and adjustment amounts) references a shared definition, a JSON number or a plain decimal string: nonNegativeAmount for prices, bounds, base prices, price hints and discount amounts, and the signed amount for modifiers and adjustment amounts. v0.9 sheets that carried prices inside the configurator no longer validate. v0.9 was otherwise an additive release on top of v0.8: the legalEntity entry's organization now also validates in reference-stub form (@type + @id, no name) so entries can reference a Commerce Organization Sheet; the inline form and all other constraints are unchanged, and v0.8 sheets remain valid once their format_version is updated. v0.8 is an additive release on top of v0.7: it adds a pagefront:featureGroup[] array for grouped, ordered technical specifications (groups of Schema.org PropertyValue entries, with an optional pagefront:presentationValue display variant per entry), a pagefront:productHighlights[] array of ordered publisher-authored selling-point strings, and a pagefront:legalEntity[] array for role-typed legal entities behind a product (closed role enum: brand_owner, licensee, authorized_representative, importer, manufacturer — EU GPSR responsible persons and similar). gtin and gtin13 now accept a string or an array of strings (regional packaging, re-releases); category now accepts the display string, a Schema.org CategoryCode object, or a mixed array of both. The pagefront:Document role enum gains repairability_index, recall_notice, and declaration_of_conformity; the pagefront:RelatedProduct relationship enum gains service. v0.8 also adds two GPSR-driven safety fields: a pagefront:safetyWarning[] array for typed, language-scoped safety warnings (text required; optional pictogram URL and open-vocabulary hazardCategory) and a pagefront:safetyNotice[] array for structured recall/safety notices (closed noticeType enum: recall, warning; closed remedy enum: repair, replacement, refund). v0.7 sheets remain valid under v0.8 once their format_version is updated. Validates the envelope and pagefront-namespaced extensions strictly; Schema.org-typed blocks permit additional unspecified properties.",
     "type": "object",
     "required": [
-        "format_version",
+        "release",
         "schema_org_version",
         "canonical_url",
         "sheet_url",
@@ -25,8 +25,9 @@ export const PRODUCT_SCHEMA = {
             "type": "string",
             "format": "uri"
         },
-        "format_version": {
-            "const": "0.9"
+        "release": {
+            "type": "string",
+            "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$"
         },
         "schema_org_version": {
             "type": "string",

package/dist/releases.d.ts

@@ -0,0 +1,36 @@
+import type { SheetType } from "./sheet-type.js";
+/**
+ * The commerce release manifest (commerce/spec/releases.json), bundled
+ * verbatim: each release and the member versions it bundles. Generated
+ * from the spec file; the drift test (test/releases.test.mjs) fails
+ * when the two diverge. Regenerate when a release is cut.
+ */
+export declare const RELEASE_MANIFEST: {
+    readonly $comment: "The commerce release manifest: each release and the member versions it bundles. Consumed by the linter; the human-readable form is releases.md.";
+    readonly vertical: "commerce";
+    readonly schema_url_template: "https://themachineweb.org/pagefront/spec/commerce/{sheet}/v{version}.json";
+    readonly releases: readonly [{
+        readonly release: "0.3.0";
+        readonly date: "2026-10-01";
+        readonly vocabulary: "0.3.0";
+        readonly sheets: {
+            readonly product: "0.9.0";
+            readonly organization: "0.3.0";
+        };
+    }];
+    readonly legacy: {
+        readonly envelope_field: "format_version";
+        readonly format_versions: readonly ["0.9"];
+        readonly schemas: {
+            readonly product: "https://themachineweb.org/pagefront/spec/commerce/product/v0.9.json";
+            readonly organization: "https://themachineweb.org/pagefront/spec/commerce/organization/v0.9.json";
+        };
+    };
+};
+/** Every release the manifest lists, in manifest order. */
+export declare const KNOWN_RELEASES: readonly string[];
+/**
+ * The sheet-spec version a release bundles for a sheet type, or
+ * undefined when the manifest does not list the release.
+ */
+export declare function sheetSpecVersionFor(release: string, sheetType: SheetType): string | undefined;

package/dist/releases.js

@@ -0,0 +1,41 @@
+/**
+ * The commerce release manifest (commerce/spec/releases.json), bundled
+ * verbatim: each release and the member versions it bundles. Generated
+ * from the spec file; the drift test (test/releases.test.mjs) fails
+ * when the two diverge. Regenerate when a release is cut.
+ */
+export const RELEASE_MANIFEST = {
+    "$comment": "The commerce release manifest: each release and the member versions it bundles. Consumed by the linter; the human-readable form is releases.md.",
+    "vertical": "commerce",
+    "schema_url_template": "https://themachineweb.org/pagefront/spec/commerce/{sheet}/v{version}.json",
+    "releases": [
+        {
+            "release": "0.3.0",
+            "date": "2026-10-01",
+            "vocabulary": "0.3.0",
+            "sheets": {
+                "product": "0.9.0",
+                "organization": "0.3.0"
+            }
+        }
+    ],
+    "legacy": {
+        "envelope_field": "format_version",
+        "format_versions": [
+            "0.9"
+        ],
+        "schemas": {
+            "product": "https://themachineweb.org/pagefront/spec/commerce/product/v0.9.json",
+            "organization": "https://themachineweb.org/pagefront/spec/commerce/organization/v0.9.json"
+        }
+    }
+};
+/** Every release the manifest lists, in manifest order. */
+export const KNOWN_RELEASES = RELEASE_MANIFEST.releases.map((r) => r.release);
+/**
+ * The sheet-spec version a release bundles for a sheet type, or
+ * undefined when the manifest does not list the release.
+ */
+export function sheetSpecVersionFor(release, sheetType) {
+    return RELEASE_MANIFEST.releases.find((r) => r.release === release)?.sheets[sheetType];
+}

package/dist/rules/org-e-002.d.ts

@@ -0,0 +1,7 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * ORG-E-002 — Sheet carries both format_version and release.
+ * The organization-sheet counterpart of PDP-E-016. Transcribed from
+ * commerce/spec/rules.md (normative).
+ */
+export declare const orgE002: Rule;

package/dist/rules/org-e-002.js

@@ -0,0 +1,13 @@
+import { BOTH_VERSION_FIELDS, bothVersionFields } from "./release-schema.js";
+/**
+ * ORG-E-002 — Sheet carries both format_version and release.
+ * The organization-sheet counterpart of PDP-E-016. Transcribed from
+ * commerce/spec/rules.md (normative).
+ */
+export const orgE002 = {
+    id: "ORG-E-002",
+    ...BOTH_VERSION_FIELDS,
+    check: bothVersionFields,
+    introduced: "release 0.3.0",
+    specReference: "organization.md#the-envelope",
+};

package/dist/rules/org-e-003.d.ts

@@ -0,0 +1,7 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * ORG-E-003 — Release / schema mismatch.
+ * The organization-sheet counterpart of PDP-E-002. Transcribed from
+ * commerce/spec/rules.md (normative).
+ */
+export declare const orgE003: Rule;

package/dist/rules/org-e-003.js

@@ -0,0 +1,13 @@
+import { RELEASE_SCHEMA_MISMATCH, releaseSchemaMismatch } from "./release-schema.js";
+/**
+ * ORG-E-003 — Release / schema mismatch.
+ * The organization-sheet counterpart of PDP-E-002. Transcribed from
+ * commerce/spec/rules.md (normative).
+ */
+export const orgE003 = {
+    id: "ORG-E-003",
+    ...RELEASE_SCHEMA_MISMATCH,
+    check: releaseSchemaMismatch("organization"),
+    introduced: "release 0.3.0",
+    specReference: "organization.md#the-envelope",
+};

package/dist/rules/pdp-e-002.d.ts

@@ -1,13 +1,7 @@
 import type { Rule } from "@pagefront/lint-core";
 /**
- * PDP-E-002 — Format version / schema mismatch.
- * Transcribed from commerce/spec/rules.md (normative).
- *
- * `$schema` is read via the rule context, per the target line. The
- * version segment is the trailing `v<version>.json` of the `$schema`
- * URL. Two quiet cases, both documented readings: `$schema` absent
- * (optional at Layer 1 — nothing to compare), and a `$schema` with no
- * parseable version segment (it declares no version, so no mismatch
- * can be asserted; the message requires `{schema_version}`).
+ * PDP-E-002 — Release / schema mismatch (until release 0.3.0: "Format
+ * version / schema mismatch"). Transcribed from commerce/spec/rules.md
+ * (normative); the check is shared with ORG-E-003 (release-schema.ts).
  */
 export declare const pdpE002: Rule;

package/dist/rules/pdp-e-002.js

@@ -1,33 +1,13 @@
+import { RELEASE_SCHEMA_MISMATCH, releaseSchemaMismatch } from "./release-schema.js";
 /**
- * PDP-E-002 — Format version / schema mismatch.
- * Transcribed from commerce/spec/rules.md (normative).
- *
- * `$schema` is read via the rule context, per the target line. The
- * version segment is the trailing `v<version>.json` of the `$schema`
- * URL. Two quiet cases, both documented readings: `$schema` absent
- * (optional at Layer 1 — nothing to compare), and a `$schema` with no
- * parseable version segment (it declares no version, so no mismatch
- * can be asserted; the message requires `{schema_version}`).
+ * PDP-E-002 — Release / schema mismatch (until release 0.3.0: "Format
+ * version / schema mismatch"). Transcribed from commerce/spec/rules.md
+ * (normative); the check is shared with ORG-E-003 (release-schema.ts).
  */
 export const pdpE002 = {
     id: "PDP-E-002",
-    title: "Format version / schema mismatch",
-    severity: "error",
-    target: "$.format_version",
-    check: (match, ctx) => {
-        const formatVersion = String(match.value);
-        const schema = ctx.sheet.$schema;
-        if (typeof schema !== "string")
-            return null;
-        const segment = /v(\d+(?:\.\d+)*)\.json$/.exec(schema);
-        if (segment === null)
-            return null;
-        return segment[1] === formatVersion
-            ? null
-            : { values: { format_version: formatVersion, schema_version: segment[1] } };
-    },
-    messageTemplate: "`format_version` is `{format_version}` but `$schema` URL declares version `{schema_version}`.",
-    remediation: "Align both fields to the same version. Whichever version was intended, update the other field to match.",
+    ...RELEASE_SCHEMA_MISMATCH,
+    check: releaseSchemaMismatch("product"),
     introduced: "v0.6",
     specReference: "product.md#the-envelope",
 };

package/dist/rules/pdp-e-016.d.ts

@@ -0,0 +1,7 @@
+import type { Rule } from "@pagefront/lint-core";
+/**
+ * PDP-E-016 — Sheet carries both format_version and release.
+ * Transcribed from commerce/spec/rules.md (normative); the check is
+ * shared with ORG-E-002 (release-schema.ts).
+ */
+export declare const pdpE016: Rule;

package/dist/rules/pdp-e-016.js

@@ -0,0 +1,13 @@
+import { BOTH_VERSION_FIELDS, bothVersionFields } from "./release-schema.js";
+/**
+ * PDP-E-016 — Sheet carries both format_version and release.
+ * Transcribed from commerce/spec/rules.md (normative); the check is
+ * shared with ORG-E-002 (release-schema.ts).
+ */
+export const pdpE016 = {
+    id: "PDP-E-016",
+    ...BOTH_VERSION_FIELDS,
+    check: bothVersionFields,
+    introduced: "release 0.3.0",
+    specReference: "product.md#the-envelope",
+};

package/dist/rules/release-schema.d.ts

@@ -0,0 +1,16 @@
+import type { CheckFn, Rule } from "@pagefront/lint-core";
+import type { SheetType } from "../sheet-type.js";
+/**
+ * Release / schema mismatch. On the release line the `$schema` version
+ * segment must be the sheet-spec version the release manifest maps the
+ * declared `release` and the sheet type to; a release the manifest does
+ * not list has no mapping and the rule is silent. On the legacy line
+ * the segment must equal `format_version`, as before. Quiet when
+ * `$schema` is absent or names no version, and when the sheet carries
+ * both fields (the both-fields rule reports that).
+ */
+export declare function releaseSchemaMismatch(sheetType: SheetType): CheckFn;
+export declare const RELEASE_SCHEMA_MISMATCH: Pick<Rule, "title" | "severity" | "target" | "messageTemplate" | "remediation">;
+/** A sheet carrying both `format_version` and `release`. */
+export declare const bothVersionFields: CheckFn;
+export declare const BOTH_VERSION_FIELDS: Pick<Rule, "title" | "severity" | "target" | "messageTemplate" | "remediation">;

package/dist/rules/release-schema.js

@@ -0,0 +1,77 @@
+import { sheetSpecVersionFor } from "../releases.js";
+/**
+ * Shared checks for the envelope's version fields, used by the product
+ * and organization catalogues (PDP-E-002 / ORG-E-003, PDP-E-016 /
+ * ORG-E-002). Transcribed from commerce/spec/rules.md (normative).
+ */
+/** The trailing `v<version>.json` of a `$schema` URL. */
+const SCHEMA_VERSION = /v(\d+(?:\.\d+)*)\.json$/;
+const SHEET_LABEL = {
+    product: "Product Sheet",
+    organization: "Organization Sheet",
+};
+/**
+ * Release / schema mismatch. On the release line the `$schema` version
+ * segment must be the sheet-spec version the release manifest maps the
+ * declared `release` and the sheet type to; a release the manifest does
+ * not list has no mapping and the rule is silent. On the legacy line
+ * the segment must equal `format_version`, as before. Quiet when
+ * `$schema` is absent or names no version, and when the sheet carries
+ * both fields (the both-fields rule reports that).
+ */
+export function releaseSchemaMismatch(sheetType) {
+    return (_match, ctx) => {
+        const { release, format_version: formatVersion, $schema: schema } = ctx.sheet;
+        if (typeof schema !== "string")
+            return null;
+        const schemaVersion = SCHEMA_VERSION.exec(schema)?.[1];
+        if (schemaVersion === undefined)
+            return null;
+        if (release !== undefined && formatVersion !== undefined)
+            return null;
+        if (typeof release === "string") {
+            const expected = sheetSpecVersionFor(release, sheetType);
+            if (expected === undefined || expected === schemaVersion)
+                return null;
+            return {
+                path: "$['release']",
+                values: {
+                    declared: `\`release\` \`${release}\` bundles ${SHEET_LABEL[sheetType]} spec \`${expected}\``,
+                    release,
+                    expected,
+                    schema_version: schemaVersion,
+                },
+            };
+        }
+        if (formatVersion !== undefined) {
+            const declared = String(formatVersion);
+            if (declared === schemaVersion)
+                return null;
+            return {
+                path: "$['format_version']",
+                values: {
+                    declared: `\`format_version\` is \`${declared}\``,
+                    format_version: declared,
+                    schema_version: schemaVersion,
+                },
+            };
+        }
+        return null;
+    };
+}
+export const RELEASE_SCHEMA_MISMATCH = {
+    title: "Release / schema mismatch",
+    severity: "error",
+    target: "$",
+    messageTemplate: "{declared} but `$schema` URL declares version `{schema_version}`.",
+    remediation: "Point `$schema` at the sheet-spec version the declared release bundles (see releases.md), or declare the release that bundles the schema the sheet was written against. On a legacy sheet, align `format_version` and the `$schema` version.",
+};
+/** A sheet carrying both `format_version` and `release`. */
+export const bothVersionFields = (_match, ctx) => ctx.sheet.release !== undefined && ctx.sheet.format_version !== undefined ? {} : null;
+export const BOTH_VERSION_FIELDS = {
+    title: "Sheet carries both format_version and release",
+    severity: "error",
+    target: "$",
+    messageTemplate: "Sheet carries both `format_version` and `release`; a sheet declares one.",
+    remediation: "Keep `release` and remove `format_version`. A sheet on the legacy draft line keeps `format_version` alone and its legacy `$schema`.",
+};

package/dist/schema-validators.d.ts

@@ -8,3 +8,5 @@ import type { ValidateFunction } from "ajv";
 
 export const validateProduct: ValidateFunction;
 export const validateOrganization: ValidateFunction;
+export const validateLegacyProduct: ValidateFunction;
+export const validateLegacyOrganization: ValidateFunction;