@tracepass/dpp-validate 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -13,6 +13,9 @@ export type { ConditionalRule } from "./rules.js";
 export { IN_SCOPE_BATTERY_CATEGORIES, BATTERY_FIELD_GATES, GATED_FIELD_KEYS, batteryFieldApplicability, gateForKey, } from "./battery-applicability.js";
 export type { Applicability, FieldGate } from "./battery-applicability.js";
 export { checkPublishReady } from "./vendor/publish-gate.js";
+export { effectiveRequired, effectiveRequiredForBattery } from "./vendor/publish-gate.js";
+export { isInScopeBatteryCategory } from "./vendor/battery-scope.js";
+export { isFieldAbsent, isFieldValueAbsent } from "./vendor/field-emptiness.js";
 export { getPartyRoles, isRequiredRole, allRolesForCategory, CATEGORY_PARTY_ROLES } from "./vendor/required-roles.js";
 export type { CategoryKey } from "./vendor/required-roles.js";
 export { derivePassportCounts } from "./vendor/counts.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,gBAAgB,EAChB,yBAAyB,EACzB,UAAU,GACX,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAI3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACtH,YAAY,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,gBAAgB,EAChB,yBAAyB,EACzB,UAAU,GACX,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAI3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACtH,YAAY,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -12,6 +12,11 @@ export { IN_SCOPE_BATTERY_CATEGORIES, BATTERY_FIELD_GATES, GATED_FIELD_KEYS, bat
 // Re-exported because a passport's publish-readiness and required economic
 // operators are part of judging whether it is compliant, not separate concerns.
 export { checkPublishReady } from "./vendor/publish-gate.js";
+// Exported alongside the gate: a caller rendering a form needs the same
+// per-category answer the gate uses, or its asterisks disagree with its verdict.
+export { effectiveRequired, effectiveRequiredForBattery } from "./vendor/publish-gate.js";
+export { isInScopeBatteryCategory } from "./vendor/battery-scope.js";
+export { isFieldAbsent, isFieldValueAbsent } from "./vendor/field-emptiness.js";
 export { getPartyRoles, isRequiredRole, allRolesForCategory, CATEGORY_PARTY_ROLES } from "./vendor/required-roles.js";
 export { derivePassportCounts } from "./vendor/counts.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAWlD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,gBAAgB,EAChB,yBAAyB,EACzB,UAAU,GACX,MAAM,4BAA4B,CAAC;AAGpC,2EAA2E;AAC3E,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAEtH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAWlD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,gBAAgB,EAChB,yBAAyB,EACzB,UAAU,GACX,MAAM,4BAA4B,CAAC;AAGpC,2EAA2E;AAC3E,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,wEAAwE;AACxE,iFAAiF;AACjF,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAEtH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/vendor/battery-scope.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which battery categories are in scope for the EU battery passport at all.
+ *
+ * Art. 77 of Reg (EU) 2023/1542 hangs the passport on LMT, EV and industrial
+ * batteries only. Portable and SLI batteries are covered by the Regulation for
+ * other duties (labelling, collection, removability) but carry NO passport
+ * obligation, and neither does industrial ≤ 2 kWh. The Commission's own data-point
+ * guidance is scoped the same way — it enumerates applicability for "EV, LMT and
+ * industrial batteries" and never addresses the other three categories.
+ *
+ * The template's `batteryCategory` enum offers all six values because it also
+ * describes batteries we hold data about; the enum is NOT the scope list. Read
+ * this module to answer "is a passport due", never the enum.
+ *
+ * Lives on its own so the compliance engine and the publish gate can share one
+ * definition without importing each other. Both did carry their own copy, kept
+ * in agreement by hand.
+ */
+/** Categories that owe a battery passport (BAT-1 / Art. 77(1)). */
+export declare const IN_SCOPE_BATTERY_CATEGORIES: readonly ["LMT", "EV", "industrial_gt_2kwh"];
+export type InScopeBatteryCategory = (typeof IN_SCOPE_BATTERY_CATEGORIES)[number];
+/**
+ * True when `category` owes a battery passport.
+ *
+ * An unset category returns `false` — absence of a category is not evidence of
+ * an obligation. Callers that need to distinguish "out of scope" from "we don't
+ * know yet" must check for `undefined` themselves; BAT-1 does exactly that so it
+ * can raise `unverifiable_conditional` rather than silently passing.
+ */
+export declare function isInScopeBatteryCategory(category: string | undefined | null): boolean;
+//# sourceMappingURL=battery-scope.d.ts.map

package/dist/vendor/battery-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"battery-scope.d.ts","sourceRoot":"","sources":["../../src/vendor/battery-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,mEAAmE;AACnE,eAAO,MAAM,2BAA2B,8CAI9B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAI/C;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAClC,OAAO,CAET"}

package/dist/vendor/battery-scope.js

@@ -0,0 +1,37 @@
+/**
+ * Which battery categories are in scope for the EU battery passport at all.
+ *
+ * Art. 77 of Reg (EU) 2023/1542 hangs the passport on LMT, EV and industrial
+ * batteries only. Portable and SLI batteries are covered by the Regulation for
+ * other duties (labelling, collection, removability) but carry NO passport
+ * obligation, and neither does industrial ≤ 2 kWh. The Commission's own data-point
+ * guidance is scoped the same way — it enumerates applicability for "EV, LMT and
+ * industrial batteries" and never addresses the other three categories.
+ *
+ * The template's `batteryCategory` enum offers all six values because it also
+ * describes batteries we hold data about; the enum is NOT the scope list. Read
+ * this module to answer "is a passport due", never the enum.
+ *
+ * Lives on its own so the compliance engine and the publish gate can share one
+ * definition without importing each other. Both did carry their own copy, kept
+ * in agreement by hand.
+ */
+/** Categories that owe a battery passport (BAT-1 / Art. 77(1)). */
+export const IN_SCOPE_BATTERY_CATEGORIES = [
+    "LMT",
+    "EV",
+    "industrial_gt_2kwh",
+];
+const IN_SCOPE = new Set(IN_SCOPE_BATTERY_CATEGORIES);
+/**
+ * True when `category` owes a battery passport.
+ *
+ * An unset category returns `false` — absence of a category is not evidence of
+ * an obligation. Callers that need to distinguish "out of scope" from "we don't
+ * know yet" must check for `undefined` themselves; BAT-1 does exactly that so it
+ * can raise `unverifiable_conditional` rather than silently passing.
+ */
+export function isInScopeBatteryCategory(category) {
+    return category != null && IN_SCOPE.has(category);
+}
+//# sourceMappingURL=battery-scope.js.map

package/dist/vendor/battery-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"battery-scope.js","sourceRoot":"","sources":["../../src/vendor/battery-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,KAAK;IACL,IAAI;IACJ,oBAAoB;CACZ,CAAC;AAKX,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,2BAA2B,CAAC,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAmC;IAEnC,OAAO,QAAQ,IAAI,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACpD,CAAC"}

package/dist/vendor/field-emptiness.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Is a passport field's value absent?
+ *
+ * This looks trivial and is not — the same question is asked in a dozen places
+ * (publish gate, compliance verdict, bulk approve, gap reports, the extraction
+ * pipeline, the review UI) and getting it subtly wrong has already cost real
+ * data twice.
+ *
+ * ── An empty ARRAY is an answer, not a gap ──
+ *
+ * `hazardousSubstances: []` asserts "we checked, there are none" — a positive
+ * compliance claim, the same kind as `svhcPresent: false`. Treating it as
+ * absent discards a declared finding and re-queues settled work.
+ *
+ * The trap is that **`String([]) === ""`**. Any check written as
+ * `String(v).trim() === ""` therefore swallows every empty array silently. A
+ * repair pass built that way flagged 60 of them, two on PUBLISHED passports,
+ * and would have wiped genuine "none apply" declarations.
+ *
+ * ── `false` and `0` are values ──
+ *
+ * `svhcPresent: false` is the ECHA register's actual answer.
+ * `recycledContentPercent: 0` is a measurement. `if (!value)` discards both,
+ * which is why that shortcut is never correct here.
+ *
+ * ── Whitespace is absent ──
+ *
+ * `"   "` is what an empty form field or a trimmed-to-nothing extraction
+ * leaves behind. The long-standing inline checks used `value === ""` and so
+ * counted a whitespace string as filled — enough to satisfy a required field
+ * in the publish gate.
+ */
+/**
+ * True when the field holds no value.
+ *
+ * Absent: `null`, `undefined`, `""`, whitespace-only strings.
+ * Present: `false`, `0`, `[]`, `{}`, and every non-blank scalar.
+ *
+ * Note `[]` and `{}` count as PRESENT. An empty collection is a declaration
+ * that the collection is empty; callers that need "no entries" should test
+ * `.length` themselves, which reads as the different question it is.
+ */
+export declare function isFieldValueAbsent(value: unknown): boolean;
+/** Convenience for the common `!field || absent(field.value)` shape. */
+export declare function isFieldAbsent(field: {
+    value?: unknown;
+} | undefined | null): boolean;
+//# sourceMappingURL=field-emptiness.d.ts.map

package/dist/vendor/field-emptiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-emptiness.d.ts","sourceRoot":"","sources":["../../src/vendor/field-emptiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI1D;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,KAAK,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAEpF"}

package/dist/vendor/field-emptiness.js

@@ -0,0 +1,54 @@
+/**
+ * Is a passport field's value absent?
+ *
+ * This looks trivial and is not — the same question is asked in a dozen places
+ * (publish gate, compliance verdict, bulk approve, gap reports, the extraction
+ * pipeline, the review UI) and getting it subtly wrong has already cost real
+ * data twice.
+ *
+ * ── An empty ARRAY is an answer, not a gap ──
+ *
+ * `hazardousSubstances: []` asserts "we checked, there are none" — a positive
+ * compliance claim, the same kind as `svhcPresent: false`. Treating it as
+ * absent discards a declared finding and re-queues settled work.
+ *
+ * The trap is that **`String([]) === ""`**. Any check written as
+ * `String(v).trim() === ""` therefore swallows every empty array silently. A
+ * repair pass built that way flagged 60 of them, two on PUBLISHED passports,
+ * and would have wiped genuine "none apply" declarations.
+ *
+ * ── `false` and `0` are values ──
+ *
+ * `svhcPresent: false` is the ECHA register's actual answer.
+ * `recycledContentPercent: 0` is a measurement. `if (!value)` discards both,
+ * which is why that shortcut is never correct here.
+ *
+ * ── Whitespace is absent ──
+ *
+ * `"   "` is what an empty form field or a trimmed-to-nothing extraction
+ * leaves behind. The long-standing inline checks used `value === ""` and so
+ * counted a whitespace string as filled — enough to satisfy a required field
+ * in the publish gate.
+ */
+/**
+ * True when the field holds no value.
+ *
+ * Absent: `null`, `undefined`, `""`, whitespace-only strings.
+ * Present: `false`, `0`, `[]`, `{}`, and every non-blank scalar.
+ *
+ * Note `[]` and `{}` count as PRESENT. An empty collection is a declaration
+ * that the collection is empty; callers that need "no entries" should test
+ * `.length` themselves, which reads as the different question it is.
+ */
+export function isFieldValueAbsent(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === "string")
+        return value.trim() === "";
+    return false;
+}
+/** Convenience for the common `!field || absent(field.value)` shape. */
+export function isFieldAbsent(field) {
+    return !field || isFieldValueAbsent(field.value);
+}
+//# sourceMappingURL=field-emptiness.js.map

package/dist/vendor/field-emptiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-emptiness.js","sourceRoot":"","sources":["../../src/vendor/field-emptiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;IAC1D,OAAO,KAAK,CAAC;AACf,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAAC,KAA6C;IACzE,OAAO,CAAC,KAAK,IAAI,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AACnD,CAAC"}

package/dist/vendor/publish-gate.d.ts

@@ -6,8 +6,19 @@
  *
  * One rule, one implementation. If the product policy for publishing
  * changes (e.g. "warnings block", "min coverage %"), change it here.
+ *
+ * ⚠️ MIRRORED INTO THE PUBLIC npm PACKAGE @tracepass/dpp-validate.
+ * `tracepass-open/packages/dpp-validate/src/vendor/publish-gate.ts` is a hand-copy of this
+ * file — nothing generates one from the other, and a stale copy fails silently
+ * (it still compiles and still returns a plausible answer). tracepass-open
+ * gates on a hash of this file in CI, so after changing it:
+ *
+ *   cd ../tracepass-open && node scripts/build-mirror-manifest.mjs \
+ *     && npm run check:mirrors
+ *
+ * and commit `mirror-manifest.json` with the code.
  */
-import type { Passport, Template } from "@tracepass/dpp-types";
+import type { Passport, Template, TemplateField } from "@tracepass/dpp-types";
 export interface PublishCheck {
     ready: boolean;
     /** Field keys that have no value set. */
@@ -27,13 +38,70 @@ export interface PublishCheck {
      */
     blockerType?: "hard" | "gap";
 }
+/**
+ * Resolves whether a template field is effectively required for a specific
+ * battery category:
+ *
+ *   1. No `requiredBy` map → fall back to `validation.required`.
+ *      This is the backward-compat path: ALL 11 non-battery templates and
+ *      any battery field without a `requiredBy` entry behave exactly as before.
+ *   2. Category present in the map → "required" is true; "conditional" and
+ *      "notApplicable" are false.
+ *   3. Category absent from the map, or unset on the passport → base required.
+ *
+ * `requiredBy` maps are keyed ONLY by the three in-scope categories, so step 3
+ * is what a portable or SLI battery would otherwise land on — see
+ * `effectiveRequiredForBattery`, which callers holding a battery passport should
+ * use instead.
+ *
+ * @param tf        A template field (from the template's `fields` array).
+ * @param category  The resolved `batteryCategory` value from the passport, or
+ *                  `undefined` when the field is unset.
+ */
+export declare function effectiveRequired(tf: Pick<TemplateField, "validation">, category: string | undefined): boolean;
+/**
+ * Battery-aware wrapper around `effectiveRequired`.
+ *
+ * A portable, SLI or industrial-≤2 kWh battery owes NO battery passport at all
+ * (Art. 77(1) — see `isInScopeBatteryCategory`), so no Annex XIII field is
+ * mandatory for it. Resolving those categories through `effectiveRequired`
+ * alone lands on the base `required` flag, which would demand the full
+ * category-agnostic field set from a battery that has no passport obligation —
+ * an obligation we would be inventing.
+ *
+ * An UNSET category still falls through to the base flag. That is deliberate:
+ * absence of a category is not evidence of exemption, and treating "not yet
+ * filled in" as "nothing required" would let a genuine EV battery publish empty.
+ * BAT-1 raises a warning for the unset case instead.
+ *
+ * Non-battery templates never reach the scope branch — they carry no
+ * `batteryCategory`, so `category` is `undefined` and behaviour is unchanged.
+ */
+export declare function effectiveRequiredForBattery(tf: Pick<TemplateField, "validation">, category: string | undefined): boolean;
+/**
+ * True when the template EXPLICITLY marks this field `notApplicable` for the
+ * given category — i.e. the Regulation says it must not be filled or displayed.
+ *
+ * Distinct from "not required" in the way that matters for a compliance
+ * surface: a `conditional` field may legitimately be filled and simply isn't
+ * mandatory, whereas a `notApplicable` one carries an instruction NOT to report
+ * it (the Annex XIII 4(b) state-of-health exclusions are the live example — an
+ * EV battery must leave the granular metrics blank and an LMT battery must
+ * leave SOCE blank). Rendering those as "not provided" reads as missing data
+ * when the truth is that there is nothing to provide.
+ *
+ * Returns false when the category is unset or the field carries no map —
+ * absence of information is never grounds for asserting non-applicability.
+ */
+export declare function notApplicableForCategory(tf: Pick<TemplateField, "validation">, category: string | undefined): boolean;
 /**
  * Returns whether `passport` satisfies every publish precondition given
  * its `template`. A passport is publish-ready iff:
  *   - status is in PUBLISHABLE_STATUSES (already-published + terminal
  *     states return ready:false with a specific reason),
- *   - every template field with validation.required has a non-empty
- *     value AND status === "approved".
+ *   - every template field whose effective required flag (resolved via
+ *     `effectiveRequired` — which consults `requiredBy` when present) is
+ *     true has a non-empty value AND status === "approved".
  *
  * `undefined` template means we can't evaluate — treat as not-ready.
  */

package/dist/vendor/publish-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publish-gate.d.ts","sourceRoot":"","sources":["../../src/vendor/publish-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,yCAAyC;IACzC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC9B;AAQD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAC7B,YAAY,CAgEd"}
+{"version":3,"file":"publish-gate.d.ts","sourceRoot":"","sources":["../../src/vendor/publish-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI9E,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,yCAAyC;IACzC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC9B;AAQD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,EACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAUT;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,EACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAKT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,EACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAIT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAC7B,YAAY,CA6Ed"}

package/dist/vendor/publish-gate.js

@@ -6,19 +6,107 @@
  *
  * One rule, one implementation. If the product policy for publishing
  * changes (e.g. "warnings block", "min coverage %"), change it here.
+ *
+ * ⚠️ MIRRORED INTO THE PUBLIC npm PACKAGE @tracepass/dpp-validate.
+ * `tracepass-open/packages/dpp-validate/src/vendor/publish-gate.ts` is a hand-copy of this
+ * file — nothing generates one from the other, and a stale copy fails silently
+ * (it still compiles and still returns a plausible answer). tracepass-open
+ * gates on a hash of this file in CI, so after changing it:
+ *
+ *   cd ../tracepass-open && node scripts/build-mirror-manifest.mjs \
+ *     && npm run check:mirrors
+ *
+ * and commit `mirror-manifest.json` with the code.
  */
+import { isInScopeBatteryCategory } from "./battery-scope.js";
+import { isFieldAbsent } from "./field-emptiness.js";
 const PUBLISHABLE_STATUSES = new Set([
     "draft",
     "in_review",
     "approved",
 ]);
+/**
+ * Resolves whether a template field is effectively required for a specific
+ * battery category:
+ *
+ *   1. No `requiredBy` map → fall back to `validation.required`.
+ *      This is the backward-compat path: ALL 11 non-battery templates and
+ *      any battery field without a `requiredBy` entry behave exactly as before.
+ *   2. Category present in the map → "required" is true; "conditional" and
+ *      "notApplicable" are false.
+ *   3. Category absent from the map, or unset on the passport → base required.
+ *
+ * `requiredBy` maps are keyed ONLY by the three in-scope categories, so step 3
+ * is what a portable or SLI battery would otherwise land on — see
+ * `effectiveRequiredForBattery`, which callers holding a battery passport should
+ * use instead.
+ *
+ * @param tf        A template field (from the template's `fields` array).
+ * @param category  The resolved `batteryCategory` value from the passport, or
+ *                  `undefined` when the field is unset.
+ */
+export function effectiveRequired(tf, category) {
+    const { requiredBy, required } = tf.validation;
+    // Path 1 & 3: no map, or category not a key in the map → base required.
+    if (!requiredBy || category === undefined || !(category in requiredBy)) {
+        return required;
+    }
+    // Path 2: explicit per-category applicability.
+    return requiredBy[category] === "required";
+}
+/**
+ * Battery-aware wrapper around `effectiveRequired`.
+ *
+ * A portable, SLI or industrial-≤2 kWh battery owes NO battery passport at all
+ * (Art. 77(1) — see `isInScopeBatteryCategory`), so no Annex XIII field is
+ * mandatory for it. Resolving those categories through `effectiveRequired`
+ * alone lands on the base `required` flag, which would demand the full
+ * category-agnostic field set from a battery that has no passport obligation —
+ * an obligation we would be inventing.
+ *
+ * An UNSET category still falls through to the base flag. That is deliberate:
+ * absence of a category is not evidence of exemption, and treating "not yet
+ * filled in" as "nothing required" would let a genuine EV battery publish empty.
+ * BAT-1 raises a warning for the unset case instead.
+ *
+ * Non-battery templates never reach the scope branch — they carry no
+ * `batteryCategory`, so `category` is `undefined` and behaviour is unchanged.
+ */
+export function effectiveRequiredForBattery(tf, category) {
+    if (category !== undefined && !isInScopeBatteryCategory(category)) {
+        return false;
+    }
+    return effectiveRequired(tf, category);
+}
+/**
+ * True when the template EXPLICITLY marks this field `notApplicable` for the
+ * given category — i.e. the Regulation says it must not be filled or displayed.
+ *
+ * Distinct from "not required" in the way that matters for a compliance
+ * surface: a `conditional` field may legitimately be filled and simply isn't
+ * mandatory, whereas a `notApplicable` one carries an instruction NOT to report
+ * it (the Annex XIII 4(b) state-of-health exclusions are the live example — an
+ * EV battery must leave the granular metrics blank and an LMT battery must
+ * leave SOCE blank). Rendering those as "not provided" reads as missing data
+ * when the truth is that there is nothing to provide.
+ *
+ * Returns false when the category is unset or the field carries no map —
+ * absence of information is never grounds for asserting non-applicability.
+ */
+export function notApplicableForCategory(tf, category) {
+    const { requiredBy } = tf.validation;
+    if (!requiredBy || category === undefined)
+        return false;
+    return requiredBy[category] === "notApplicable";
+}
 /**
  * Returns whether `passport` satisfies every publish precondition given
  * its `template`. A passport is publish-ready iff:
  *   - status is in PUBLISHABLE_STATUSES (already-published + terminal
  *     states return ready:false with a specific reason),
- *   - every template field with validation.required has a non-empty
- *     value AND status === "approved".
+ *   - every template field whose effective required flag (resolved via
+ *     `effectiveRequired` — which consults `requiredBy` when present) is
+ *     true has a non-empty value AND status === "approved".
  *
  * `undefined` template means we can't evaluate — treat as not-ready.
  */
@@ -50,16 +138,29 @@ export function checkPublishReady(passport, template) {
             blockerType: "hard",
         };
     }
+    // Read the passport's battery category so effectiveRequired can resolve
+    // per-category applicability. For non-battery passports (no batteryCategory
+    // field) this is always undefined and effectiveRequired falls back to the
+    // plain `required` boolean — no behaviour change for other templates.
+    const categoryField = passport.fields["batteryCategory"];
+    const category = categoryField && categoryField.value != null && categoryField.value !== ""
+        ? String(categoryField.value)
+        : undefined;
     const missingFields = [];
     const unapprovedFields = [];
     for (const tf of template.fields) {
-        if (!tf.validation.required)
+        // `anticipated` fields rest on a delegated act that has not been adopted,
+        // so no instrument in force compels the data and their absence cannot block
+        // publication. Skip them before the required check.
+        if (tf.validation.anticipated)
+            continue;
+        if (!effectiveRequiredForBattery(tf, category))
             continue;
         const f = passport.fields[tf.key];
-        if (!f ||
-            f.value === null ||
-            f.value === undefined ||
-            f.value === "") {
+        // Shared helper: `[]` stays a valid answer ("none apply"), while a
+        // whitespace-only string now counts as missing — the inline `=== ""` it
+        // replaces let "   " satisfy a required field and publish a blank.
+        if (isFieldAbsent(f)) {
             missingFields.push(tf.key);
         }
         else if (f.status !== "approved") {

package/dist/vendor/publish-gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"publish-gate.js","sourceRoot":"","sources":["../../src/vendor/publish-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwBH,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAqB;IACvD,OAAO;IACP,WAAW;IACX,UAAU;CACX,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAkB,EAClB,QAA8B;IAE9B,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QACpC,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,aAAa,EAAE,EAAE;YACjB,gBAAgB,EAAE,EAAE;YACpB,MAAM,EAAE,mBAAmB;YAC3B,WAAW,EAAE,MAAM;SACpB,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/C,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,aAAa,EAAE,EAAE;YACjB,gBAAgB,EAAE,EAAE;YACpB,MAAM,EAAE,8BAA8B,QAAQ,CAAC,MAAM,EAAE;YACvD,WAAW,EAAE,MAAM;SACpB,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,aAAa,EAAE,EAAE;YACjB,gBAAgB,EAAE,EAAE;YACpB,MAAM,EAAE,kBAAkB;YAC1B,WAAW,EAAE,MAAM;SACpB,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,MAAM,gBAAgB,GAAa,EAAE,CAAC;IAEtC,KAAK,MAAM,EAAE,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ;YAAE,SAAS;QACtC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;QAClC,IACE,CAAC,CAAC;YACF,CAAC,CAAC,KAAK,KAAK,IAAI;YAChB,CAAC,CAAC,KAAK,KAAK,SAAS;YACrB,CAAC,CAAC,KAAK,KAAK,EAAE,EACd,CAAC;YACD,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACnC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAAC;IAClE,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,MAAM,UAAU,CAAC,CAAC;IAC5E,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,MAAM,eAAe,CAAC,CAAC;IAEvF,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,aAAa;QACb,gBAAgB;QAChB,MAAM,EAAE,oBAAoB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAC9C,WAAW,EAAE,KAAK;KACnB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"publish-gate.js","sourceRoot":"","sources":["../../src/vendor/publish-gate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tracepass/dpp-validate",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Evaluate an EU Digital Product Passport against its category field-spec — a three-tier compliance verdict with regulation-cited findings. Pure functions, no third-party runtime dependencies.",
   "keywords": [
     "digital-product-passport",
@@ -45,7 +45,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@tracepass/dpp-types": "^0.4.0"
+    "@tracepass/dpp-types": "^0.5.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3"