@lssm/lib.overlay-engine 0.0.0-canary-20251217062943 → 0.0.0-canary-20251217072406

package/dist/index.js

@@ -1 +1,8 @@
-import{OVERLAY_SCOPE_ORDER as e,defineOverlay as t}from"./spec.js";import{assertOverlayValid as n,defaultOverlayValidator as r,validateOverlaySpec as i}from"./validator.js";import{OverlayRegistry as a}from"./registry.js";import{applyOverlayModifications as o}from"./merger.js";import{OverlayEngine as s}from"./runtime.js";import{canonicalizeOverlay as c,signOverlay as l,stripSignature as u,verifyOverlaySignature as d}from"./signer.js";export{e as OVERLAY_SCOPE_ORDER,s as OverlayEngine,a as OverlayRegistry,o as applyOverlayModifications,n as assertOverlayValid,c as canonicalizeOverlay,r as defaultOverlayValidator,t as defineOverlay,l as signOverlay,u as stripSignature,i as validateOverlaySpec,d as verifyOverlaySignature};
+import { OVERLAY_SCOPE_ORDER, defineOverlay } from "./spec.js";
+import { assertOverlayValid, defaultOverlayValidator, validateOverlaySpec } from "./validator.js";
+import { OverlayRegistry } from "./registry.js";
+import { applyOverlayModifications } from "./merger.js";
+import { OverlayEngine } from "./runtime.js";
+import { canonicalizeOverlay, signOverlay, stripSignature, verifyOverlaySignature } from "./signer.js";
+
+export { OVERLAY_SCOPE_ORDER, OverlayEngine, OverlayRegistry, applyOverlayModifications, assertOverlayValid, canonicalizeOverlay, defaultOverlayValidator, defineOverlay, signOverlay, stripSignature, validateOverlaySpec, verifyOverlaySignature };

package/dist/merger.js

@@ -1 +1,106 @@
-function e(e,r,i={}){if(!r.length)return e;let a=e.fields.map(e=>({key:e.key,field:{...e},hidden:e.visible===!1})),o=new Map(a.map(e=>[e.key,e])),s=e.fields.map(e=>e.key),c=(e,t)=>{if(i.strict)throw Error(`Overlay "${t}" referenced unknown field "${e}".`)};r.forEach(e=>{e.modifications.forEach(r=>{switch(r.type){case`hideField`:{let t=o.get(r.field);if(!t)return c(r.field,e.overlayId);t.hidden=!0,t.field.visible=!1;break}case`renameLabel`:{let t=o.get(r.field);if(!t)return c(r.field,e.overlayId);t.field.label=r.newLabel;break}case`setDefault`:{let t=o.get(r.field);if(!t)return c(r.field,e.overlayId);t.field.defaultValue=r.value;break}case`addHelpText`:{let t=o.get(r.field);if(!t)return c(r.field,e.overlayId);t.field.helpText=r.text;break}case`makeRequired`:{let t=o.get(r.field);if(!t)return c(r.field,e.overlayId);t.field.required=r.required??!0;break}case`reorderFields`:{let{filtered:a,missing:l}=t(r.fields,o);l.length&&i.strict&&l.forEach(t=>c(t,e.overlayId)),s=n(s,a);break}default:break}})});let l=[],u=new Set;return s.forEach(e=>{let t=o.get(e);!t||t.hidden||(u.add(e),l.push(t.field))}),a.forEach(e=>{e.hidden||u.has(e.key)||l.push(e.field)}),l.forEach((e,t)=>{e.order=t,e.visible=!0}),{...e,fields:l}}function t(e,t){let n=[],r=[],i=new Set;return e.forEach(e=>{if(e?.trim()){if(!t.has(e)){r.push(e);return}i.has(e)||(i.add(e),n.push(e))}}),{filtered:n,missing:r}}function n(e,t){if(!t.length)return e;let n=new Set(t),r=e.filter(e=>!n.has(e));return[...t,...r]}export{e as applyOverlayModifications};
+//#region src/merger.ts
+function applyOverlayModifications(target, overlays, options = {}) {
+	if (!overlays.length) return target;
+	const states = target.fields.map((field) => ({
+		key: field.key,
+		field: { ...field },
+		hidden: field.visible === false
+	}));
+	const fieldMap = new Map(states.map((state) => [state.key, state]));
+	let orderSequence = target.fields.map((field) => field.key);
+	const handleMissing = (field, overlayId) => {
+		if (options.strict) throw new Error(`Overlay "${overlayId}" referenced unknown field "${field}".`);
+	};
+	overlays.forEach((overlay) => {
+		overlay.modifications.forEach((modification) => {
+			switch (modification.type) {
+				case "hideField": {
+					const state = fieldMap.get(modification.field);
+					if (!state) return handleMissing(modification.field, overlay.overlayId);
+					state.hidden = true;
+					state.field.visible = false;
+					break;
+				}
+				case "renameLabel": {
+					const state = fieldMap.get(modification.field);
+					if (!state) return handleMissing(modification.field, overlay.overlayId);
+					state.field.label = modification.newLabel;
+					break;
+				}
+				case "setDefault": {
+					const state = fieldMap.get(modification.field);
+					if (!state) return handleMissing(modification.field, overlay.overlayId);
+					state.field.defaultValue = modification.value;
+					break;
+				}
+				case "addHelpText": {
+					const state = fieldMap.get(modification.field);
+					if (!state) return handleMissing(modification.field, overlay.overlayId);
+					state.field.helpText = modification.text;
+					break;
+				}
+				case "makeRequired": {
+					const state = fieldMap.get(modification.field);
+					if (!state) return handleMissing(modification.field, overlay.overlayId);
+					state.field.required = modification.required ?? true;
+					break;
+				}
+				case "reorderFields": {
+					const { filtered, missing } = normalizeOrderList(modification.fields, fieldMap);
+					if (missing.length && options.strict) missing.forEach((field) => handleMissing(field, overlay.overlayId));
+					orderSequence = applyReorder(orderSequence, filtered);
+					break;
+				}
+				default: break;
+			}
+		});
+	});
+	const visibleFields = [];
+	const seen = /* @__PURE__ */ new Set();
+	orderSequence.forEach((key) => {
+		const state = fieldMap.get(key);
+		if (!state || state.hidden) return;
+		seen.add(key);
+		visibleFields.push(state.field);
+	});
+	states.forEach((state) => {
+		if (state.hidden || seen.has(state.key)) return;
+		visibleFields.push(state.field);
+	});
+	visibleFields.forEach((field, index) => {
+		field.order = index;
+		field.visible = true;
+	});
+	return {
+		...target,
+		fields: visibleFields
+	};
+}
+function normalizeOrderList(fields, fieldMap) {
+	const filtered = [];
+	const missing = [];
+	const seen = /* @__PURE__ */ new Set();
+	fields.forEach((field) => {
+		if (!field?.trim()) return;
+		if (!fieldMap.has(field)) {
+			missing.push(field);
+			return;
+		}
+		if (seen.has(field)) return;
+		seen.add(field);
+		filtered.push(field);
+	});
+	return {
+		filtered,
+		missing
+	};
+}
+function applyReorder(sequence, orderedFields) {
+	if (!orderedFields.length) return sequence;
+	const orderedSet = new Set(orderedFields);
+	const remainder = sequence.filter((key) => !orderedSet.has(key));
+	return [...orderedFields, ...remainder];
+}
+
+//#endregion
+export { applyOverlayModifications };

package/dist/react.js

@@ -1 +1,22 @@
-import{useMemo as e}from"react";function t(t,n,r=[]){return e(()=>t?t.apply(n):{target:n.target,overlaysApplied:[]},[t,n,...r])}function n(e,n,r=[]){return t(e,n,r).target.fields}export{t as useOverlay,n as useOverlayFields};
+import { useMemo } from "react";
+
+//#region src/react.ts
+function useOverlay(engine, params, deps = []) {
+	return useMemo(() => {
+		if (!engine) return {
+			target: params.target,
+			overlaysApplied: []
+		};
+		return engine.apply(params);
+	}, [
+		engine,
+		params,
+		...deps
+	]);
+}
+function useOverlayFields(engine, params, deps = []) {
+	return useOverlay(engine, params, deps).target.fields;
+}
+
+//#endregion
+export { useOverlay, useOverlayFields };

package/dist/registry.js

@@ -1 +1,106 @@
-import{defaultOverlayValidator as e}from"./validator.js";const t=[`capability`,`workflow`,`dataView`,`presentation`,`operation`],n={tenantId:8,role:4,userId:16,device:2,tags:1};var r=class{overlays=new Map;constructor(e={}){this.options=e}register(t,n){if(!n?.skipValidation){let n=(this.options.validator??e)(t);if(!n.valid){let e=n.issues.map(e=>`${e.code}: ${e.message}`).join(`; `);throw Error(`Overlay "${t.overlayId}" failed validation: ${e}`)}}let r=this.ensureSigned(t),i=this.getKey(r.overlayId,r.version),o={overlay:r,specificity:a(r.appliesTo),registeredAt:Date.now()};return this.overlays.set(i,o),r}unregister(e,t){if(t){this.overlays.delete(this.getKey(e,t));return}for(let t of Array.from(this.overlays.keys()))t.startsWith(`${e}@`)&&this.overlays.delete(t)}list(){return Array.from(this.overlays.values()).map(e=>e.overlay)}get(e,t){return this.overlays.get(this.getKey(e,t))?.overlay}forContext(e){return Array.from(this.overlays.values()).filter(t=>o(t.overlay.appliesTo,e)).sort((e,t)=>e.specificity===t.specificity?e.registeredAt-t.registeredAt:e.specificity-t.specificity).map(e=>e.overlay)}clear(){this.overlays.clear()}size(){return this.overlays.size}ensureSigned(e){if(i(e)){if(!e.signature?.signature&&!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" is missing a signature.`);return e}if(!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" must be signed before registration.`);return e}getKey(e,t){return`${e}@${t}`}};function i(e){return!!e.signature}function a(e){let t=0;return Object.keys(n).forEach(r=>{(r===`tags`?Array.isArray(e.tags)&&e.tags.length>0:e[r])&&(t+=n[r])}),t}function o(e,n){for(let r of t){let t=e[r];if(t&&t!==n[r])return!1}if(e.tenantId&&e.tenantId!==n.tenantId||e.role&&e.role!==n.role||e.userId&&e.userId!==n.userId||e.device&&e.device!==n.device)return!1;if(e.tags?.length){if(!n.tags?.length)return!1;let t=new Set(n.tags);if(!e.tags.every(e=>t.has(e)))return!1}return!0}export{r as OverlayRegistry};
+import { defaultOverlayValidator } from "./validator.js";
+
+//#region src/registry.ts
+const TARGET_KEYS = [
+	"capability",
+	"workflow",
+	"dataView",
+	"presentation",
+	"operation"
+];
+const SCOPE_WEIGHTS = {
+	tenantId: 8,
+	role: 4,
+	userId: 16,
+	device: 2,
+	tags: 1
+};
+var OverlayRegistry = class {
+	overlays = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.options = options;
+	}
+	register(overlay, options) {
+		if (!options?.skipValidation) {
+			const result = (this.options.validator ?? defaultOverlayValidator)(overlay);
+			if (!result.valid) {
+				const reason = result.issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
+				throw new Error(`Overlay "${overlay.overlayId}" failed validation: ${reason}`);
+			}
+		}
+		const normalized = this.ensureSigned(overlay);
+		const key = this.getKey(normalized.overlayId, normalized.version);
+		const stored = {
+			overlay: normalized,
+			specificity: computeSpecificity(normalized.appliesTo),
+			registeredAt: Date.now()
+		};
+		this.overlays.set(key, stored);
+		return normalized;
+	}
+	unregister(overlayId, version) {
+		if (version) {
+			this.overlays.delete(this.getKey(overlayId, version));
+			return;
+		}
+		for (const key of Array.from(this.overlays.keys())) if (key.startsWith(`${overlayId}@`)) this.overlays.delete(key);
+	}
+	list() {
+		return Array.from(this.overlays.values()).map((entry) => entry.overlay);
+	}
+	get(overlayId, version) {
+		return this.overlays.get(this.getKey(overlayId, version))?.overlay;
+	}
+	forContext(query) {
+		return Array.from(this.overlays.values()).filter((entry) => matches(entry.overlay.appliesTo, query)).sort((a, b) => {
+			if (a.specificity !== b.specificity) return a.specificity - b.specificity;
+			return a.registeredAt - b.registeredAt;
+		}).map((entry) => entry.overlay);
+	}
+	clear() {
+		this.overlays.clear();
+	}
+	size() {
+		return this.overlays.size;
+	}
+	ensureSigned(input) {
+		if (isSignedOverlay(input)) {
+			if (!input.signature?.signature && !this.options.allowUnsigned) throw new Error(`Overlay "${input.overlayId}" is missing a signature.`);
+			return input;
+		}
+		if (!this.options.allowUnsigned) throw new Error(`Overlay "${input.overlayId}" must be signed before registration.`);
+		return input;
+	}
+	getKey(overlayId, version) {
+		return `${overlayId}@${version}`;
+	}
+};
+function isSignedOverlay(spec) {
+	return Boolean(spec.signature);
+}
+function computeSpecificity(appliesTo) {
+	let score = 0;
+	Object.keys(SCOPE_WEIGHTS).forEach((key) => {
+		if (key === "tags" ? Array.isArray(appliesTo.tags) && appliesTo.tags.length > 0 : Boolean(appliesTo[key])) score += SCOPE_WEIGHTS[key];
+	});
+	return score;
+}
+function matches(appliesTo, ctx) {
+	for (const key of TARGET_KEYS) {
+		const expected = appliesTo[key];
+		if (expected && expected !== ctx[key]) return false;
+	}
+	if (appliesTo.tenantId && appliesTo.tenantId !== ctx.tenantId) return false;
+	if (appliesTo.role && appliesTo.role !== ctx.role) return false;
+	if (appliesTo.userId && appliesTo.userId !== ctx.userId) return false;
+	if (appliesTo.device && appliesTo.device !== ctx.device) return false;
+	if (appliesTo.tags?.length) {
+		if (!ctx.tags?.length) return false;
+		const ctxTags = new Set(ctx.tags);
+		if (!appliesTo.tags.every((tag) => ctxTags.has(tag))) return false;
+	}
+	return true;
+}
+
+//#endregion
+export { OverlayRegistry };

package/dist/runtime.js

@@ -1 +1,53 @@
-import{applyOverlayModifications as e}from"./merger.js";var t=class{registry;audit;constructor(e){this.registry=e.registry,this.audit=e.audit}apply(t){let r=t.overlays??this.registry.forContext({capability:t.capability,workflow:t.workflow,dataView:t.dataView,presentation:t.presentation,operation:t.operation,tenantId:t.tenantId,role:t.role,userId:t.userId,device:t.device,tags:t.tags}),i=e(t.target,r,{strict:t.strict}),a=n(t);return r.forEach(e=>{this.audit?.({overlay:{overlayId:e.overlayId,version:e.version},context:a,timestamp:new Date().toISOString()})}),{target:i,overlaysApplied:r}}};function n(e){return{tenantId:e.tenantId,role:e.role,userId:e.userId,device:e.device,tags:e.tags}}export{t as OverlayEngine};
+import { applyOverlayModifications } from "./merger.js";
+
+//#region src/runtime.ts
+var OverlayEngine = class {
+	registry;
+	audit;
+	constructor(options) {
+		this.registry = options.registry;
+		this.audit = options.audit;
+	}
+	apply(params) {
+		const overlays = params.overlays ?? this.registry.forContext({
+			capability: params.capability,
+			workflow: params.workflow,
+			dataView: params.dataView,
+			presentation: params.presentation,
+			operation: params.operation,
+			tenantId: params.tenantId,
+			role: params.role,
+			userId: params.userId,
+			device: params.device,
+			tags: params.tags
+		});
+		const merged = applyOverlayModifications(params.target, overlays, { strict: params.strict });
+		const context = extractContext(params);
+		overlays.forEach((overlay) => {
+			this.audit?.({
+				overlay: {
+					overlayId: overlay.overlayId,
+					version: overlay.version
+				},
+				context,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		});
+		return {
+			target: merged,
+			overlaysApplied: overlays
+		};
+	}
+};
+function extractContext(params) {
+	return {
+		tenantId: params.tenantId,
+		role: params.role,
+		userId: params.userId,
+		device: params.device,
+		tags: params.tags
+	};
+}
+
+//#endregion
+export { OverlayEngine };

package/dist/signer.js

@@ -1 +1,62 @@
-import e from"fast-json-stable-stringify";import{constants as t,createPrivateKey as n,createPublicKey as r,sign as i,verify as a}from"crypto";function o(e,a,o={}){let s=o.algorithm??`ed25519`,l=typeof a==`string`||Buffer.isBuffer(a)?n(a):a,d=Buffer.from(c(e),`utf8`),f;if(s===`ed25519`)f=i(null,d,l);else if(s===`rsa-pss-sha256`)f=i(`sha256`,d,{key:l,padding:t.RSA_PKCS1_PSS_PADDING,saltLength:32});else throw Error(`Unsupported overlay signature algorithm: ${s}`);let p=o.publicKey??r(l).export({format:`pem`,type:`spki`}).toString();return{...e,signature:{algorithm:s,signature:f.toString(`base64`),publicKey:p,keyId:o.keyId,issuedAt:u(o.issuedAt)??new Date().toISOString(),expiresAt:u(o.expiresAt),metadata:o.metadata}}}function s(e){if(!e.signature?.signature)throw Error(`Overlay "${e.overlayId}" is missing signature metadata.`);let n=Buffer.from(c(e),`utf8`),i=Buffer.from(e.signature.signature,`base64`),o=r(e.signature.publicKey);if(e.signature.algorithm===`ed25519`)return a(null,n,o,i);if(e.signature.algorithm===`rsa-pss-sha256`)return a(`sha256`,n,{key:o,padding:t.RSA_PKCS1_PSS_PADDING,saltLength:32},i);throw Error(`Unsupported overlay signature algorithm: ${e.signature.algorithm}`)}function c(t){let{signature:n,...r}=t;return e(r)}function l(e){let{signature:t,...n}=e;return{...n}}function u(e){if(e)return typeof e==`string`?new Date(e).toISOString():e.toISOString()}export{c as canonicalizeOverlay,o as signOverlay,l as stripSignature,s as verifyOverlaySignature};
+import stringify from "fast-json-stable-stringify";
+import { constants, createPrivateKey, createPublicKey, sign, verify } from "crypto";
+
+//#region src/signer.ts
+function signOverlay(spec, privateKey, options = {}) {
+	const algorithm = options.algorithm ?? "ed25519";
+	const keyObject = typeof privateKey === "string" || Buffer.isBuffer(privateKey) ? createPrivateKey(privateKey) : privateKey;
+	const payload = Buffer.from(canonicalizeOverlay(spec), "utf8");
+	let rawSignature;
+	if (algorithm === "ed25519") rawSignature = sign(null, payload, keyObject);
+	else if (algorithm === "rsa-pss-sha256") rawSignature = sign("sha256", payload, {
+		key: keyObject,
+		padding: constants.RSA_PKCS1_PSS_PADDING,
+		saltLength: 32
+	});
+	else throw new Error(`Unsupported overlay signature algorithm: ${algorithm}`);
+	const publicKey = options.publicKey ?? createPublicKey(keyObject).export({
+		format: "pem",
+		type: "spki"
+	}).toString();
+	return {
+		...spec,
+		signature: {
+			algorithm,
+			signature: rawSignature.toString("base64"),
+			publicKey,
+			keyId: options.keyId,
+			issuedAt: toIso(options.issuedAt) ?? (/* @__PURE__ */ new Date()).toISOString(),
+			expiresAt: toIso(options.expiresAt),
+			metadata: options.metadata
+		}
+	};
+}
+function verifyOverlaySignature(overlay) {
+	if (!overlay.signature?.signature) throw new Error(`Overlay "${overlay.overlayId}" is missing signature metadata.`);
+	const payload = Buffer.from(canonicalizeOverlay(overlay), "utf8");
+	const signature = Buffer.from(overlay.signature.signature, "base64");
+	const publicKey = createPublicKey(overlay.signature.publicKey);
+	if (overlay.signature.algorithm === "ed25519") return verify(null, payload, publicKey, signature);
+	if (overlay.signature.algorithm === "rsa-pss-sha256") return verify("sha256", payload, {
+		key: publicKey,
+		padding: constants.RSA_PKCS1_PSS_PADDING,
+		saltLength: 32
+	}, signature);
+	throw new Error(`Unsupported overlay signature algorithm: ${overlay.signature.algorithm}`);
+}
+function canonicalizeOverlay(spec) {
+	const { signature, ...rest } = spec;
+	return stringify(rest);
+}
+function stripSignature(spec) {
+	const { signature, ...rest } = spec;
+	return { ...rest };
+}
+function toIso(value) {
+	if (!value) return;
+	if (typeof value === "string") return new Date(value).toISOString();
+	return value.toISOString();
+}
+
+//#endregion
+export { canonicalizeOverlay, signOverlay, stripSignature, verifyOverlaySignature };

package/dist/spec.js

@@ -1 +1,14 @@
-const e=[`tenantId`,`role`,`userId`,`device`,`tags`];function t(e){return e}export{e as OVERLAY_SCOPE_ORDER,t as defineOverlay};
+//#region src/spec.ts
+const OVERLAY_SCOPE_ORDER = [
+	"tenantId",
+	"role",
+	"userId",
+	"device",
+	"tags"
+];
+function defineOverlay(spec) {
+	return spec;
+}
+
+//#endregion
+export { OVERLAY_SCOPE_ORDER, defineOverlay };

package/dist/validator.js

@@ -1 +1,100 @@
-const e=[`capability`,`workflow`,`dataView`,`presentation`,`operation`],t=e=>n(e);function n(t){let n=[];return t.overlayId?.trim()||n.push({code:`overlay.id`,message:`overlayId is required`,path:[`overlayId`]}),t.version?.trim()||n.push({code:`overlay.version`,message:`version is required`,path:[`version`]}),e.some(e=>{let n=t.appliesTo?.[e];return typeof n==`string`&&n.trim().length>0})||n.push({code:`overlay.target`,message:`Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).`,path:[`appliesTo`]}),t.modifications?.length?t.modifications.forEach((e,t)=>{r(e,[`modifications`,String(t)],n)}):n.push({code:`overlay.modifications.empty`,message:`Overlay must include at least one modification.`,path:[`modifications`]}),{valid:n.length===0,issues:n}}function r(e,t,n){let r=(e,r,i)=>{n.push({code:e,message:r,path:i?[...t,...i]:t})};switch(i(e)&&(e.field?.trim()||r(`overlay.mod.field`,`field is required for this modification`,[`field`])),e.type){case`renameLabel`:e.newLabel?.trim()||r(`overlay.mod.renameLabel.newLabel`,`newLabel is required`,[`newLabel`]);break;case`reorderFields`:{e.fields?.length||r(`overlay.mod.reorderFields.fields`,`fields list cannot be empty`,[`fields`]);let t=new Set;for(let n of e.fields??[]){if(!n?.trim()){r(`overlay.mod.reorderFields.fields.blank`,`fields entries must be non-empty`);break}if(t.has(n)){r(`overlay.mod.reorderFields.fields.duplicate`,`field "${n}" was listed multiple times`);break}t.add(n)}break}case`setDefault`:e.value===void 0&&r(`overlay.mod.setDefault.value`,`value is required`,[`value`]);break;case`addHelpText`:e.text?.trim()||r(`overlay.mod.addHelpText.text`,`text is required`,[`text`]);break;case`makeRequired`:case`hideField`:break;default:{let t=e;throw Error(`Unsupported overlay modification ${t?.type??`unknown`}`)}}}function i(e){return`field`in e}function a(e,n=t){let r=n(e);if(!r.valid){let t=r.issues.map(e=>`${e.code}: ${e.message}`).join(`; `);throw Error(`Invalid OverlaySpec "${e.overlayId}": ${t}`)}}export{a as assertOverlayValid,t as defaultOverlayValidator,n as validateOverlaySpec};
+//#region src/validator.ts
+const TARGET_KEYS = [
+	"capability",
+	"workflow",
+	"dataView",
+	"presentation",
+	"operation"
+];
+const defaultOverlayValidator = (spec) => validateOverlaySpec(spec);
+function validateOverlaySpec(spec) {
+	const issues = [];
+	if (!spec.overlayId?.trim()) issues.push({
+		code: "overlay.id",
+		message: "overlayId is required",
+		path: ["overlayId"]
+	});
+	if (!spec.version?.trim()) issues.push({
+		code: "overlay.version",
+		message: "version is required",
+		path: ["version"]
+	});
+	if (!TARGET_KEYS.some((key) => {
+		const value = spec.appliesTo?.[key];
+		return typeof value === "string" && value.trim().length > 0;
+	})) issues.push({
+		code: "overlay.target",
+		message: "Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).",
+		path: ["appliesTo"]
+	});
+	if (!spec.modifications?.length) issues.push({
+		code: "overlay.modifications.empty",
+		message: "Overlay must include at least one modification.",
+		path: ["modifications"]
+	});
+	else spec.modifications.forEach((mod, idx) => {
+		validateModification(mod, ["modifications", String(idx)], issues);
+	});
+	return {
+		valid: issues.length === 0,
+		issues
+	};
+}
+function validateModification(modification, path, issues) {
+	const push = (code, message, extraPath) => {
+		issues.push({
+			code,
+			message,
+			path: extraPath ? [...path, ...extraPath] : path
+		});
+	};
+	if (isFieldModification(modification)) {
+		if (!modification.field?.trim()) push("overlay.mod.field", "field is required for this modification", ["field"]);
+	}
+	switch (modification.type) {
+		case "renameLabel":
+			if (!modification.newLabel?.trim()) push("overlay.mod.renameLabel.newLabel", "newLabel is required", ["newLabel"]);
+			break;
+		case "reorderFields": {
+			if (!modification.fields?.length) push("overlay.mod.reorderFields.fields", "fields list cannot be empty", ["fields"]);
+			const seen = /* @__PURE__ */ new Set();
+			for (const field of modification.fields ?? []) {
+				if (!field?.trim()) {
+					push("overlay.mod.reorderFields.fields.blank", "fields entries must be non-empty");
+					break;
+				}
+				if (seen.has(field)) {
+					push("overlay.mod.reorderFields.fields.duplicate", `field "${field}" was listed multiple times`);
+					break;
+				}
+				seen.add(field);
+			}
+			break;
+		}
+		case "setDefault":
+			if (modification.value === void 0) push("overlay.mod.setDefault.value", "value is required", ["value"]);
+			break;
+		case "addHelpText":
+			if (!modification.text?.trim()) push("overlay.mod.addHelpText.text", "text is required", ["text"]);
+			break;
+		case "makeRequired":
+		case "hideField": break;
+		default: {
+			const exhaustive = modification;
+			throw new Error(`Unsupported overlay modification ${exhaustive?.type ?? "unknown"}`);
+		}
+	}
+}
+function isFieldModification(mod) {
+	return "field" in mod;
+}
+function assertOverlayValid(spec, validator = defaultOverlayValidator) {
+	const result = validator(spec);
+	if (!result.valid) {
+		const message = result.issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
+		throw new Error(`Invalid OverlaySpec "${spec.overlayId}": ${message}`);
+	}
+}
+
+//#endregion
+export { assertOverlayValid, defaultOverlayValidator, validateOverlaySpec };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.overlay-engine",
-  "version": "0.0.0-canary-20251217062943",
+  "version": "0.0.0-canary-20251217072406",
   "description": "Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,7 @@
     "test": "bun run"
   },
   "dependencies": {
-    "@lssm/lib.contracts": "0.0.0-canary-20251217062943",
+    "@lssm/lib.contracts": "0.0.0-canary-20251217072406",
     "fast-json-stable-stringify": "^2.1.0"
   },
   "peerDependencies": {
@@ -36,8 +36,8 @@
     }
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.0.0-canary-20251217062943",
-    "@lssm/tool.typescript": "0.0.0-canary-20251217062943",
+    "@lssm/tool.tsdown": "0.0.0-canary-20251217072406",
+    "@lssm/tool.typescript": "0.0.0-canary-20251217072406",
     "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },