@lssm/lib.contracts 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217073102

package/dist/policy/docs/policy.docblock.js

@@ -1 +1,22 @@
-import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.policy`,title:`PolicySpec & PolicyEngine`,summary:"`PolicySpec` gives a declarative, typed home for access-control logic covering:",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/policy`,tags:[`tech`,`contracts`,`policy`],body:"# PolicySpec & PolicyEngine\n\n## Purpose\n\n`PolicySpec` gives a declarative, typed home for access-control logic covering:\n- **Who** can perform an action (ABAC/ReBAC style rules)\n- **What** they can access (resources + optional field-level overrides)\n- **When** special conditions apply (contextual expressions)\n- **How** PII should be handled (consent/retention hints)\n\n`PolicyEngine` evaluates one or more policies and returns an `allow`/`deny` decision, field-level outcomes, and PII metadata suitable for downstream enforcement (`SpecRegistry` → `ctx.decide`).\n\n## Location\n\n- Types & registry: `packages/libs/contracts/src/policy/spec.ts`\n- Runtime evaluation: `packages/libs/contracts/src/policy/engine.ts`\n- Tests: `packages/.../policy/engine.test.ts`\n\n## `PolicySpec`\n\n```ts\nexport interface PolicySpec {\n  meta: PolicyMeta;          // ownership metadata + { name, version, scope? }\n  rules: PolicyRule[];       // allow/deny rules for actions\n  fieldPolicies?: FieldPolicyRule[];\n  pii?: { fields: string[]; consentRequired?: boolean; retentionDays?: number };\n  relationships?: RelationshipDefinition[];\n  consents?: ConsentDefinition[];\n  rateLimits?: RateLimitDefinition[];\n  opa?: { package: string; decision?: string };\n}\n```\n\n- `PolicyRule`\n  - `effect`: `'allow' | 'deny'`\n  - `actions`: e.g., `['read', 'write', 'delete']` (string namespace is flexible)\n  - `subject`: `{ roles?: string[]; attributes?: { attr: matcher } }`\n  - `resource`: `{ type: string; fields?: string[]; attributes?: {...} }`\n  - `relationships`: `{ relation, objectId?, objectType? }[]` → ReBAC checks (use `objectId: '$resource'` to target the current resource)\n  - `requiresConsent`: `['consent_id']` → references spec-level consent definitions\n  - `flags`: feature flags that must be enabled (`DecisionContext.flags`)\n  - `rateLimit`: string reference to `rateLimits` entry or inline object `{ rpm, key?, windowSeconds?, burst? }`\n  - `escalate`: `'human_review' | null` to indicate manual approval\n  - `conditions`: optional expression snippets evaluated against `{ subject, resource, context }`\n- `FieldPolicyRule`\n  - `field`: dot-path string (e.g., `contact.email`)\n  - `actions`: subset of `['read', 'write']`\n  - Same `subject` / `resource` / `conditions` shape\n  - Useful for redacting specific fields, even when the global action is allowed\n- `RelationshipDefinition`\n  - Canonical tuples for relationship graph (`subjectType`, `relation`, `objectType`, `transitive?`)\n- `ConsentDefinition`\n  - `{ id, scope, purpose, lawfulBasis?, expiresInDays?, required? }`\n- `RateLimitDefinition`\n  - `{ id, rpm, key?, windowSeconds?, burst? }`\n- `PolicyRef`\n  - `{ name: string; version: number }` → attach to contract specs / workflows\n\n## Registry\n\n```ts\nconst registry = new PolicyRegistry();\nregistry.register(CorePolicySpec);\nconst spec = registry.get('core.default', 1);\n```\n\nGuarantees uniqueness per `(name, version)` and exposes helpers to resolve highest versions.\n\n## Engine\n\n```ts\nconst engine = new PolicyEngine(policyRegistry);\n\nconst decision = engine.decide({\n  action: 'read',\n  subject: { roles: ['admin'] },\n  resource: { type: 'resident', fields: ['contact.email'] },\n  policies: [{ name: 'core.default', version: 1 }],\n});\n/*\n{\n  effect: 'allow',\n  reason: 'core.default',\n  fieldDecisions: [{ field: 'contact.email', effect: 'allow' }],\n  pii: { fields: ['contact.email'], consentRequired: true }\n}\n*/\n```\n\n- First matching **deny** wins; otherwise the first **allow** is returned.\n- Field policies are aggregated across referenced policies:\n  - Later denies override earlier allows for a given field.\n  - Returned as `fieldDecisions` to simplify downstream masking.\n- PII metadata is surfaced when defined to help adapt logging/telemetry.\n\n### Expression Support\n\nConditions accept small JS snippets (e.g., `subject.attributes.orgId === context.orgId`). The engine runs them in a constrained scope (`subject`, `resource`, `context`) without access to global state.\n\n### ReBAC & Relationships\n\n- Provide relationship tuples via `PolicySpec.relationships` for documentation/validation.\n- Reference them inside rules with `relationships: [{ relation: 'manager_of', objectType: 'resident', objectId: '$resource' }]`.\n- The execution context must populate `subject.relationships` (`[{ relation, object, objectType }]`) for the engine to evaluate ReBAC guards.\n\n### Consent & Rate Limits\n\n- Declare reusable consent definitions under `consents`. Rules list the IDs they require; if a user session lacks the consent (`DecisionContext.consents`), the engine returns `effect: 'deny'` with `reason: 'consent_required'` and enumerates missing consents.\n- Attach rate limits either inline or via `rateLimits` references. When a rule matches, the engine surfaces `{ rpm, key, windowSeconds?, burst? }` so callers can feed it to shared limiters.\n\n### OPA Adapter\n\n- `OPAPolicyAdapter` bridges engine decisions to Open Policy Agent (OPA). It forwards the evaluation context + policies to OPA and merges any override result (`effect`, `reason`, `fieldDecisions`, `requiredConsents`).\n- Use when migrating to OPA policies or running defense-in-depth: call `engine.decide()`, then pass the preliminary decision to `adapter.evaluate(...)`. The adapter marks merged decisions with `evaluatedBy: 'opa'`.\n- OPA inputs include meta, rules, relationships, rate limits, and consent catalogs to simplify policy authoring on the OPA side.\n\n## Contract Integration\n\n`ContractSpec.policy` now supports:\n\n```ts\npolicy: {\n  auth: 'anonymous' | 'user' | 'admin';\n  ...\n  policies?: PolicyRef[];                // policies evaluated before execution\n  fieldPolicies?: {                      // field hints (read/write) per policy\n    field: string;\n    actions: ('read' | 'write')[];\n    policy?: PolicyRef;\n  }[];\n}\n```\n\nAdapters can resolve refs through a shared `PolicyEngine` and populate `ctx.decide` so `SpecRegistry.execute` benefits from centralized enforcement.\n\n## Authoring Guidelines\n\n1. Prefer **allow-by-default** policies but explicitly deny sensitive flows (defense-in-depth).\n2. Keep rule scopes narrow (per feature/operation) and compose multiple `PolicyRef`s when necessary.\n3. Store PII field lists here to avoid duplication across logs/telemetry.\n4. Use explicit rule reasons for auditability and better developer feedback.\n5. Treat versioning seriously; bump `meta.version` whenever behavior changes.\n\n## Future Enhancements\n\n- Richer expression language (composable predicates, time-based conditions).\n- Multi-tenant relationship graph services (store/resolve relationships at scale).\n- Tooling that auto-generates docs/tests for policies referenced in specs.\n\n"}];e(t);export{t as tech_contracts_policy_DocBlocks};
+import { registerDocBlocks } from "../../docs/registry.js";
+import "../../registry.js";
+
+//#region src/policy/docs/policy.docblock.ts
+const tech_contracts_policy_DocBlocks = [{
+	id: "docs.tech.contracts.policy",
+	title: "PolicySpec & PolicyEngine",
+	summary: "`PolicySpec` gives a declarative, typed home for access-control logic covering:",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/policy",
+	tags: [
+		"tech",
+		"contracts",
+		"policy"
+	],
+	body: "# PolicySpec & PolicyEngine\n\n## Purpose\n\n`PolicySpec` gives a declarative, typed home for access-control logic covering:\n- **Who** can perform an action (ABAC/ReBAC style rules)\n- **What** they can access (resources + optional field-level overrides)\n- **When** special conditions apply (contextual expressions)\n- **How** PII should be handled (consent/retention hints)\n\n`PolicyEngine` evaluates one or more policies and returns an `allow`/`deny` decision, field-level outcomes, and PII metadata suitable for downstream enforcement (`SpecRegistry` → `ctx.decide`).\n\n## Location\n\n- Types & registry: `packages/libs/contracts/src/policy/spec.ts`\n- Runtime evaluation: `packages/libs/contracts/src/policy/engine.ts`\n- Tests: `packages/.../policy/engine.test.ts`\n\n## `PolicySpec`\n\n```ts\nexport interface PolicySpec {\n  meta: PolicyMeta;          // ownership metadata + { name, version, scope? }\n  rules: PolicyRule[];       // allow/deny rules for actions\n  fieldPolicies?: FieldPolicyRule[];\n  pii?: { fields: string[]; consentRequired?: boolean; retentionDays?: number };\n  relationships?: RelationshipDefinition[];\n  consents?: ConsentDefinition[];\n  rateLimits?: RateLimitDefinition[];\n  opa?: { package: string; decision?: string };\n}\n```\n\n- `PolicyRule`\n  - `effect`: `'allow' | 'deny'`\n  - `actions`: e.g., `['read', 'write', 'delete']` (string namespace is flexible)\n  - `subject`: `{ roles?: string[]; attributes?: { attr: matcher } }`\n  - `resource`: `{ type: string; fields?: string[]; attributes?: {...} }`\n  - `relationships`: `{ relation, objectId?, objectType? }[]` → ReBAC checks (use `objectId: '$resource'` to target the current resource)\n  - `requiresConsent`: `['consent_id']` → references spec-level consent definitions\n  - `flags`: feature flags that must be enabled (`DecisionContext.flags`)\n  - `rateLimit`: string reference to `rateLimits` entry or inline object `{ rpm, key?, windowSeconds?, burst? }`\n  - `escalate`: `'human_review' | null` to indicate manual approval\n  - `conditions`: optional expression snippets evaluated against `{ subject, resource, context }`\n- `FieldPolicyRule`\n  - `field`: dot-path string (e.g., `contact.email`)\n  - `actions`: subset of `['read', 'write']`\n  - Same `subject` / `resource` / `conditions` shape\n  - Useful for redacting specific fields, even when the global action is allowed\n- `RelationshipDefinition`\n  - Canonical tuples for relationship graph (`subjectType`, `relation`, `objectType`, `transitive?`)\n- `ConsentDefinition`\n  - `{ id, scope, purpose, lawfulBasis?, expiresInDays?, required? }`\n- `RateLimitDefinition`\n  - `{ id, rpm, key?, windowSeconds?, burst? }`\n- `PolicyRef`\n  - `{ name: string; version: number }` → attach to contract specs / workflows\n\n## Registry\n\n```ts\nconst registry = new PolicyRegistry();\nregistry.register(CorePolicySpec);\nconst spec = registry.get('core.default', 1);\n```\n\nGuarantees uniqueness per `(name, version)` and exposes helpers to resolve highest versions.\n\n## Engine\n\n```ts\nconst engine = new PolicyEngine(policyRegistry);\n\nconst decision = engine.decide({\n  action: 'read',\n  subject: { roles: ['admin'] },\n  resource: { type: 'resident', fields: ['contact.email'] },\n  policies: [{ name: 'core.default', version: 1 }],\n});\n/*\n{\n  effect: 'allow',\n  reason: 'core.default',\n  fieldDecisions: [{ field: 'contact.email', effect: 'allow' }],\n  pii: { fields: ['contact.email'], consentRequired: true }\n}\n*/\n```\n\n- First matching **deny** wins; otherwise the first **allow** is returned.\n- Field policies are aggregated across referenced policies:\n  - Later denies override earlier allows for a given field.\n  - Returned as `fieldDecisions` to simplify downstream masking.\n- PII metadata is surfaced when defined to help adapt logging/telemetry.\n\n### Expression Support\n\nConditions accept small JS snippets (e.g., `subject.attributes.orgId === context.orgId`). The engine runs them in a constrained scope (`subject`, `resource`, `context`) without access to global state.\n\n### ReBAC & Relationships\n\n- Provide relationship tuples via `PolicySpec.relationships` for documentation/validation.\n- Reference them inside rules with `relationships: [{ relation: 'manager_of', objectType: 'resident', objectId: '$resource' }]`.\n- The execution context must populate `subject.relationships` (`[{ relation, object, objectType }]`) for the engine to evaluate ReBAC guards.\n\n### Consent & Rate Limits\n\n- Declare reusable consent definitions under `consents`. Rules list the IDs they require; if a user session lacks the consent (`DecisionContext.consents`), the engine returns `effect: 'deny'` with `reason: 'consent_required'` and enumerates missing consents.\n- Attach rate limits either inline or via `rateLimits` references. When a rule matches, the engine surfaces `{ rpm, key, windowSeconds?, burst? }` so callers can feed it to shared limiters.\n\n### OPA Adapter\n\n- `OPAPolicyAdapter` bridges engine decisions to Open Policy Agent (OPA). It forwards the evaluation context + policies to OPA and merges any override result (`effect`, `reason`, `fieldDecisions`, `requiredConsents`).\n- Use when migrating to OPA policies or running defense-in-depth: call `engine.decide()`, then pass the preliminary decision to `adapter.evaluate(...)`. The adapter marks merged decisions with `evaluatedBy: 'opa'`.\n- OPA inputs include meta, rules, relationships, rate limits, and consent catalogs to simplify policy authoring on the OPA side.\n\n## Contract Integration\n\n`ContractSpec.policy` now supports:\n\n```ts\npolicy: {\n  auth: 'anonymous' | 'user' | 'admin';\n  ...\n  policies?: PolicyRef[];                // policies evaluated before execution\n  fieldPolicies?: {                      // field hints (read/write) per policy\n    field: string;\n    actions: ('read' | 'write')[];\n    policy?: PolicyRef;\n  }[];\n}\n```\n\nAdapters can resolve refs through a shared `PolicyEngine` and populate `ctx.decide` so `SpecRegistry.execute` benefits from centralized enforcement.\n\n## Authoring Guidelines\n\n1. Prefer **allow-by-default** policies but explicitly deny sensitive flows (defense-in-depth).\n2. Keep rule scopes narrow (per feature/operation) and compose multiple `PolicyRef`s when necessary.\n3. Store PII field lists here to avoid duplication across logs/telemetry.\n4. Use explicit rule reasons for auditability and better developer feedback.\n5. Treat versioning seriously; bump `meta.version` whenever behavior changes.\n\n## Future Enhancements\n\n- Richer expression language (composable predicates, time-based conditions).\n- Multi-tenant relationship graph services (store/resolve relationships at scale).\n- Tooling that auto-generates docs/tests for policies referenced in specs.\n\n"
+}];
+registerDocBlocks(tech_contracts_policy_DocBlocks);
+
+//#endregion
+export { tech_contracts_policy_DocBlocks };

package/dist/policy/engine.js

@@ -1 +1,223 @@
-var e=class{constructor(e){this.registry=e}decide(e){let t=this.resolvePolicies(e.policies),n,r,i;for(let a of t){let t=this.matchRuleSet(a,e);if(t){if(t.rule.effect===`deny`)return{effect:`deny`,reason:t.rule.reason??a.meta.name,requiredConsents:t.missingConsents.length?t.missingConsents:void 0,evaluatedBy:`engine`};if(t.rule.effect===`allow`){if(t.missingConsents.length)return{effect:`deny`,reason:`consent_required`,requiredConsents:t.missingConsents,evaluatedBy:`engine`};n||=t.rule.reason??a.meta.name,!r&&t.rateLimit&&(r=t.rateLimit),!i&&t.rule.escalate&&(i=t.rule.escalate)}}}let a=this.evaluateFields(t,e),o=t.find(e=>e.pii)?.pii;return{effect:n?`allow`:`deny`,reason:n,rateLimit:r,escalate:i===void 0?void 0:i,fieldDecisions:a.length?a:void 0,pii:o,evaluatedBy:`engine`}}resolvePolicies(e){let t=[];for(let n of e){let e=this.registry.get(n.name,n.version);if(!e)throw Error(`PolicyEngine: policy not found ${n.name}.v${n.version}`);t.push(e)}return t}matchRuleSet(e,t){let s;for(let l of e.rules){if(!l.actions.includes(t.action)||!n(l,t.subject)||!r(l,t.resource)||!i(l,t)||!a(l.relationships,t)||!o(l,t))continue;let d={rule:l,missingConsents:c(l,e,t),rateLimit:u(l,e,t)};if(l.effect===`deny`)return d;l.effect===`allow`&&!s&&(s=d)}return s}evaluateFields(e,i){let a=new Map;for(let s of e)if(s.fieldPolicies)for(let e of s.fieldPolicies){if(!e.actions.includes(t(i.action))||!n(e,i.subject)||!r(e,i.resource)||!o(e,i))continue;let c=a.get(e.field);e.effect===`deny`?a.set(e.field,{field:e.field,effect:`deny`,reason:e.reason??s.meta.name}):c||a.set(e.field,{field:e.field,effect:`allow`,reason:e.reason??s.meta.name})}return[...a.values()]}};function t(e){return e.startsWith(`write`)?`write`:`read`}function n(e,t){let n=e.subject;if(!n)return!0;if(n.roles?.length){let e=t.roles??[];if(!n.roles.some(t=>e.includes(t)))return!1}if(n.attributes){let e=t.attributes??{};if(!s(n.attributes,e))return!1}return!0}function r(e,t){let n=e.resource;if(!n)return!0;if(n.type&&n.type!==t.type)return!1;if(n.fields?.length){let e=t.fields??[];if(!n.fields.some(t=>e.includes(t)))return!1}if(n.attributes){let e=t.attributes??{};if(!s(n.attributes,e))return!1}return!0}function i(e,t){if(!e.flags?.length)return!0;let n=new Set;if(t.flags)for(let e of t.flags)n.add(e);let r=t.subject.attributes?.featureFlags;if(Array.isArray(r))for(let e of r)n.add(e);return e.flags.every(e=>n.has(e))}function a(e,t){if(!e||e.length===0)return!0;let n=t.subject.relationships??[],r=p(t.resource),i=t.resource.type;return e.every(e=>n.some(t=>t.relation!==e.relation||!(!e.objectType||t.objectType===e.objectType||e.objectType===i)?!1:e.objectId?e.objectId===`$resource`?r?t.object===r:t.object===i||t.objectType===i:t.object===e.objectId:!0))}function o(e,t){return!e.conditions||e.conditions.length===0?!0:e.conditions.every(e=>d(e.expression,t))}function s(e,t){for(let[n,r]of Object.entries(e)){let e=t[n];if(r.exists&&e===void 0||r.equals!==void 0&&e!==r.equals||r.oneOf&&!r.oneOf.includes(e))return!1}return!0}function c(e,t,n){if(!e.requiresConsent?.length)return[];let r=new Set(n.consents??[]),i=e.requiresConsent.filter(e=>!r.has(e));return i.length===0?[]:l(t,i)}function l(e,t){let n=e.consents??[];return t.map(t=>n.find(e=>e.id===t)??{id:t,scope:`unspecified`,purpose:`unspecified`,description:`Consent "${t}" required by ${e.meta.name}`,required:!0})}function u(e,t,n){if(!e.rateLimit)return;let r=typeof e.rateLimit==`string`?(t.rateLimits??[]).find(t=>t.id===e.rateLimit):e.rateLimit;if(!r)throw Error(`PolicyEngine: rate limit "${String(e.rateLimit)}" not declared in ${t.meta.name}`);return{rpm:r.rpm,key:r.key??n.resource.type,windowSeconds:r.windowSeconds,burst:r.burst}}function d(e,t){let n=e.trim();if(!n)return!0;let r={subject:t.subject,resource:t.resource,context:t.context??{}};try{return!!Function(`subject`,`resource`,`context`,`return (${f(n)});`)(r.subject,r.resource,r.context)}catch{return!1}}function f(e){return e.replace(/&&/g,`&&`).replace(/\|\|/g,`||`)}function p(e){if(e.id)return e.id;let t=e.attributes?.id;if(typeof t==`string`)return t;if(typeof t==`number`)return String(t)}export{e as PolicyEngine};
+//#region src/policy/engine.ts
+var PolicyEngine = class {
+	constructor(registry) {
+		this.registry = registry;
+	}
+	decide(input) {
+		const policies = this.resolvePolicies(input.policies);
+		let allowReason;
+		let appliedRateLimit;
+		let escalate;
+		for (const policy of policies) {
+			const match = this.matchRuleSet(policy, input);
+			if (!match) continue;
+			if (match.rule.effect === "deny") return {
+				effect: "deny",
+				reason: match.rule.reason ?? policy.meta.name,
+				requiredConsents: match.missingConsents.length ? match.missingConsents : void 0,
+				evaluatedBy: "engine"
+			};
+			if (match.rule.effect === "allow") {
+				if (match.missingConsents.length) return {
+					effect: "deny",
+					reason: "consent_required",
+					requiredConsents: match.missingConsents,
+					evaluatedBy: "engine"
+				};
+				if (!allowReason) allowReason = match.rule.reason ?? policy.meta.name;
+				if (!appliedRateLimit && match.rateLimit) appliedRateLimit = match.rateLimit;
+				if (!escalate && match.rule.escalate) escalate = match.rule.escalate;
+			}
+		}
+		const fieldDecisions = this.evaluateFields(policies, input);
+		const pii = policies.find((p) => p.pii)?.pii;
+		return {
+			effect: allowReason ? "allow" : "deny",
+			reason: allowReason,
+			rateLimit: appliedRateLimit,
+			escalate: typeof escalate === "undefined" ? void 0 : escalate,
+			fieldDecisions: fieldDecisions.length ? fieldDecisions : void 0,
+			pii,
+			evaluatedBy: "engine"
+		};
+	}
+	resolvePolicies(refs) {
+		const specs = [];
+		for (const ref of refs) {
+			const spec = this.registry.get(ref.name, ref.version);
+			if (!spec) throw new Error(`PolicyEngine: policy not found ${ref.name}.v${ref.version}`);
+			specs.push(spec);
+		}
+		return specs;
+	}
+	matchRuleSet(policy, input) {
+		let allowMatch;
+		for (const rule of policy.rules) {
+			if (!rule.actions.includes(input.action)) continue;
+			if (!matchesSubject(rule, input.subject)) continue;
+			if (!matchesResource(rule, input.resource)) continue;
+			if (!matchesFlags(rule, input)) continue;
+			if (!matchesRelationships(rule.relationships, input)) continue;
+			if (!matchesConditions(rule, input)) continue;
+			const evaluation = {
+				rule,
+				missingConsents: collectMissingConsents(rule, policy, input),
+				rateLimit: resolveRateLimit(rule, policy, input)
+			};
+			if (rule.effect === "deny") return evaluation;
+			if (rule.effect === "allow" && !allowMatch) allowMatch = evaluation;
+		}
+		return allowMatch;
+	}
+	evaluateFields(policies, input) {
+		const out = /* @__PURE__ */ new Map();
+		for (const policy of policies) {
+			if (!policy.fieldPolicies) continue;
+			for (const rule of policy.fieldPolicies) {
+				if (!rule.actions.includes(mapActionToFieldAction(input.action))) continue;
+				if (!matchesSubject(rule, input.subject)) continue;
+				if (!matchesResource(rule, input.resource)) continue;
+				if (!matchesConditions(rule, input)) continue;
+				const existing = out.get(rule.field);
+				if (rule.effect === "deny") out.set(rule.field, {
+					field: rule.field,
+					effect: "deny",
+					reason: rule.reason ?? policy.meta.name
+				});
+				else if (!existing) out.set(rule.field, {
+					field: rule.field,
+					effect: "allow",
+					reason: rule.reason ?? policy.meta.name
+				});
+			}
+		}
+		return [...out.values()];
+	}
+};
+function mapActionToFieldAction(action) {
+	if (action.startsWith("write")) return "write";
+	return "read";
+}
+function matchesSubject(rule, subject) {
+	const matcher = rule.subject;
+	if (!matcher) return true;
+	if (matcher.roles?.length) {
+		const roles = subject.roles ?? [];
+		if (!matcher.roles.some((role) => roles.includes(role))) return false;
+	}
+	if (matcher.attributes) {
+		const attributes = subject.attributes ?? {};
+		if (!matchAttributes(matcher.attributes, attributes)) return false;
+	}
+	return true;
+}
+function matchesResource(rule, resource) {
+	const matcher = rule.resource;
+	if (!matcher) return true;
+	if (matcher.type && matcher.type !== resource.type) return false;
+	if (matcher.fields?.length) {
+		const targetFields = resource.fields ?? [];
+		if (!matcher.fields.some((field) => targetFields.includes(field))) return false;
+	}
+	if (matcher.attributes) {
+		const attributes = resource.attributes ?? {};
+		if (!matchAttributes(matcher.attributes, attributes)) return false;
+	}
+	return true;
+}
+function matchesFlags(rule, input) {
+	if (!rule.flags?.length) return true;
+	const available = /* @__PURE__ */ new Set();
+	if (input.flags) for (const flag of input.flags) available.add(flag);
+	const attributeFlags = input.subject.attributes?.featureFlags;
+	if (Array.isArray(attributeFlags)) for (const flag of attributeFlags) available.add(flag);
+	return rule.flags.every((flag) => available.has(flag));
+}
+function matchesRelationships(matchers, input) {
+	if (!matchers || matchers.length === 0) return true;
+	const relationships = input.subject.relationships ?? [];
+	const resourceId = getResourceId(input.resource);
+	const resourceType = input.resource.type;
+	return matchers.every((matcher) => relationships.some((relation) => {
+		if (relation.relation !== matcher.relation) return false;
+		if (!(!matcher.objectType || relation.objectType === matcher.objectType || matcher.objectType === resourceType)) return false;
+		if (!matcher.objectId) return true;
+		if (matcher.objectId === "$resource") {
+			if (resourceId) return relation.object === resourceId;
+			return relation.object === resourceType || relation.objectType === resourceType;
+		}
+		return relation.object === matcher.objectId;
+	}));
+}
+function matchesConditions(rule, input) {
+	if (!rule.conditions || rule.conditions.length === 0) return true;
+	return rule.conditions.every((condition) => evaluateCondition(condition.expression, input));
+}
+function matchAttributes(matcher, actual) {
+	for (const [key, attrMatcher] of Object.entries(matcher)) {
+		const value = actual[key];
+		if (attrMatcher.exists && typeof value === "undefined") return false;
+		if (typeof attrMatcher.equals !== "undefined") {
+			if (value !== attrMatcher.equals) return false;
+		}
+		if (attrMatcher.oneOf && !attrMatcher.oneOf.includes(value)) return false;
+	}
+	return true;
+}
+function collectMissingConsents(rule, policy, input) {
+	if (!rule.requiresConsent?.length) return [];
+	const granted = new Set(input.consents ?? []);
+	const missingIds = rule.requiresConsent.filter((id) => !granted.has(id));
+	if (missingIds.length === 0) return [];
+	return resolveConsentDefinitions(policy, missingIds);
+}
+function resolveConsentDefinitions(policy, ids) {
+	const catalog = policy.consents ?? [];
+	return ids.map((id) => {
+		return catalog.find((consent) => consent.id === id) ?? {
+			id,
+			scope: "unspecified",
+			purpose: "unspecified",
+			description: `Consent "${id}" required by ${policy.meta.name}`,
+			required: true
+		};
+	});
+}
+function resolveRateLimit(rule, policy, input) {
+	if (!rule.rateLimit) return void 0;
+	const definition = typeof rule.rateLimit === "string" ? (policy.rateLimits ?? []).find((item) => item.id === rule.rateLimit) : rule.rateLimit;
+	if (!definition) throw new Error(`PolicyEngine: rate limit "${String(rule.rateLimit)}" not declared in ${policy.meta.name}`);
+	return {
+		rpm: definition.rpm,
+		key: definition.key ?? input.resource.type,
+		windowSeconds: definition.windowSeconds,
+		burst: definition.burst
+	};
+}
+function evaluateCondition(expression, input) {
+	const trimmed = expression.trim();
+	if (!trimmed) return true;
+	const context = {
+		subject: input.subject,
+		resource: input.resource,
+		context: input.context ?? {}
+	};
+	try {
+		const result = new Function("subject", "resource", "context", `return (${transformExpression(trimmed)});`)(context.subject, context.resource, context.context);
+		return Boolean(result);
+	} catch (_error) {
+		return false;
+	}
+}
+function transformExpression(expression) {
+	return expression.replace(/&&/g, "&&").replace(/\|\|/g, "||");
+}
+function getResourceId(resource) {
+	if (resource.id) return resource.id;
+	const candidate = resource.attributes?.id;
+	if (typeof candidate === "string") return candidate;
+	if (typeof candidate === "number") return String(candidate);
+}
+
+//#endregion
+export { PolicyEngine };

package/dist/policy/opa-adapter.js

@@ -1 +1,71 @@
-var e=class{constructor(e,t){this.client=e,this.options=t}async evaluate(e,r,i){let a=t(e,r,i),o=await this.client.evaluate(this.options.decisionPath,a),s=this.options.mapResult?this.options.mapResult(o):o;if(!s)return{...i,evaluatedBy:i.evaluatedBy??`engine`};let c=s,l=n(r,i.requiredConsents??[],c.requiredConsents??[]);return{...i,effect:c.effect??i.effect,reason:c.reason??i.reason,fieldDecisions:c.fieldDecisions??i.fieldDecisions,requiredConsents:l.length?l:void 0,evaluatedBy:`opa`}}};function t(e,t,n){return{context:e,decision:n,policies:t.map(e=>({meta:e.meta,rules:e.rules,fieldPolicies:e.fieldPolicies,pii:e.pii,relationships:e.relationships,consents:e.consents,rateLimits:e.rateLimits}))}}function n(e,t,n){if(n.length===0)return t;let i=new Set(t.map(e=>e.id)),a=[...t];for(let t of n){if(i.has(t))continue;let n=r(e,t);n&&(a.push(n),i.add(n.id))}return a}function r(e,t){for(let n of e){let e=n.consents?.find(e=>e.id===t);if(e)return e}return{id:t,scope:`unspecified`,purpose:`unspecified`,description:`Consent "${t}" returned by OPA`,required:!0}}export{e as OPAPolicyAdapter,t as buildOPAInput};
+//#region src/policy/opa-adapter.ts
+var OPAPolicyAdapter = class {
+	constructor(client, options) {
+		this.client = client;
+		this.options = options;
+	}
+	async evaluate(context, policies, engineDecision) {
+		const input = buildOPAInput(context, policies, engineDecision);
+		const raw = await this.client.evaluate(this.options.decisionPath, input);
+		const resolved = this.options.mapResult ? this.options.mapResult(raw) : raw;
+		if (!resolved) return {
+			...engineDecision,
+			evaluatedBy: engineDecision.evaluatedBy ?? "engine"
+		};
+		const opaResult = resolved;
+		const mergedRequiredConsents = mergeRequiredConsents(policies, engineDecision.requiredConsents ?? [], opaResult.requiredConsents ?? []);
+		return {
+			...engineDecision,
+			effect: opaResult.effect ?? engineDecision.effect,
+			reason: opaResult.reason ?? engineDecision.reason,
+			fieldDecisions: opaResult.fieldDecisions ?? engineDecision.fieldDecisions,
+			requiredConsents: mergedRequiredConsents.length ? mergedRequiredConsents : void 0,
+			evaluatedBy: "opa"
+		};
+	}
+};
+function buildOPAInput(context, policies, engineDecision) {
+	return {
+		context,
+		decision: engineDecision,
+		policies: policies.map((policy) => ({
+			meta: policy.meta,
+			rules: policy.rules,
+			fieldPolicies: policy.fieldPolicies,
+			pii: policy.pii,
+			relationships: policy.relationships,
+			consents: policy.consents,
+			rateLimits: policy.rateLimits
+		}))
+	};
+}
+function mergeRequiredConsents(policies, existing, incomingIds) {
+	if (incomingIds.length === 0) return existing;
+	const existingIds = new Set(existing.map((consent) => consent.id));
+	const merged = [...existing];
+	for (const id of incomingIds) {
+		if (existingIds.has(id)) continue;
+		const resolved = resolveConsentAcrossPolicies(policies, id);
+		if (resolved) {
+			merged.push(resolved);
+			existingIds.add(resolved.id);
+		}
+	}
+	return merged;
+}
+function resolveConsentAcrossPolicies(policies, id) {
+	for (const policy of policies) {
+		const match = policy.consents?.find((consent) => consent.id === id);
+		if (match) return match;
+	}
+	return {
+		id,
+		scope: "unspecified",
+		purpose: "unspecified",
+		description: `Consent "${id}" returned by OPA`,
+		required: true
+	};
+}
+
+//#endregion
+export { OPAPolicyAdapter, buildOPAInput };

package/dist/policy/spec.js

@@ -1 +1,33 @@
-const e=(e,t)=>`${e}.v${t}`;var t=class{items=new Map;register(t){let n=e(t.meta.name,t.meta.version);if(this.items.has(n))throw Error(`Duplicate policy ${n}`);return this.items.set(n,t),this}list(){return[...this.items.values()]}get(t,n){if(n!=null)return this.items.get(e(t,n));let r,i=-1/0;for(let e of this.items.values())e.meta.name===t&&e.meta.version>i&&(i=e.meta.version,r=e);return r}};function n(t){return e(t.name,t.version)}export{t as PolicyRegistry,n as makePolicyKey};
+//#region src/policy/spec.ts
+const policyKey = (name, version) => `${name}.v${version}`;
+var PolicyRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	register(spec) {
+		const key = policyKey(spec.meta.name, spec.meta.version);
+		if (this.items.has(key)) throw new Error(`Duplicate policy ${key}`);
+		this.items.set(key, spec);
+		return this;
+	}
+	list() {
+		return [...this.items.values()];
+	}
+	get(name, version) {
+		if (version != null) return this.items.get(policyKey(name, version));
+		let candidate;
+		let max = -Infinity;
+		for (const spec of this.items.values()) {
+			if (spec.meta.name !== name) continue;
+			if (spec.meta.version > max) {
+				max = spec.meta.version;
+				candidate = spec;
+			}
+		}
+		return candidate;
+	}
+};
+function makePolicyKey(ref) {
+	return policyKey(ref.name, ref.version);
+}
+
+//#endregion
+export { PolicyRegistry, makePolicyKey };

package/dist/presentations/docs/presentations-conventions.docblock.js

@@ -1,8 +1,22 @@
-import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.presentations-conventions`,title:`Presentations Conventions (A11y & i18n)`,summary:"- Always provide `meta.description` (≥ 3 chars) — used by a11y/docs/agents.",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/presentations-conventions`,tags:[`tech`,`contracts`,`presentations-conventions`],body:`## Presentations Conventions (A11y & i18n)
+import { registerDocBlocks } from "../../docs/registry.js";
+import "../../registry.js";
 
-- Always provide \`meta.description\` (≥ 3 chars) — used by a11y/docs/agents.
-- Prefer source = BlockNote for rich guides; use component key for interactive flows.
-- i18n strings belong in host apps; descriptors carry keys/defaults only.
-- Target selection: include only what you intend to support to avoid drift.
-- PII: declare JSON-like paths under \`policy.pii\`; engine redacts in outputs.
-`}];e(t);export{t as tech_contracts_presentations_conventions_DocBlocks};
+//#region src/presentations/docs/presentations-conventions.docblock.ts
+const tech_contracts_presentations_conventions_DocBlocks = [{
+	id: "docs.tech.contracts.presentations-conventions",
+	title: "Presentations Conventions (A11y & i18n)",
+	summary: "- Always provide `meta.description` (≥ 3 chars) — used by a11y/docs/agents.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/presentations-conventions",
+	tags: [
+		"tech",
+		"contracts",
+		"presentations-conventions"
+	],
+	body: "## Presentations Conventions (A11y & i18n)\n\n- Always provide `meta.description` (≥ 3 chars) — used by a11y/docs/agents.\n- Prefer source = BlockNote for rich guides; use component key for interactive flows.\n- i18n strings belong in host apps; descriptors carry keys/defaults only.\n- Target selection: include only what you intend to support to avoid drift.\n- PII: declare JSON-like paths under `policy.pii`; engine redacts in outputs.\n"
+}];
+registerDocBlocks(tech_contracts_presentations_conventions_DocBlocks);
+
+//#endregion
+export { tech_contracts_presentations_conventions_DocBlocks };

package/dist/presentations.backcompat.js

@@ -1 +1,47 @@
-function e(e){return e.content.kind===`web_component`?{meta:{...e.meta},policy:e.policy,source:{type:`component`,framework:e.content.framework,componentKey:e.content.componentKey,props:e.content.props},targets:[`react`,`application/json`,`application/xml`]}:e.content.kind===`markdown`?{meta:{...e.meta},policy:e.policy,source:{type:`blocknotejs`,docJson:e.content.content??e.content.resourceUri??``},targets:[`markdown`,`application/json`,`application/xml`]}:{meta:{...e.meta},policy:e.policy,source:{type:`blocknotejs`,docJson:{kind:`data`,mimeType:e.content.mimeType,model:`schema`}},targets:[`application/json`,`application/xml`]}}export{e as toV2FromV1};
+//#region src/presentations.backcompat.ts
+function toV2FromV1(v1) {
+	if (v1.content.kind === "web_component") return {
+		meta: { ...v1.meta },
+		policy: v1.policy,
+		source: {
+			type: "component",
+			framework: v1.content.framework,
+			componentKey: v1.content.componentKey,
+			props: v1.content.props
+		},
+		targets: [
+			"react",
+			"application/json",
+			"application/xml"
+		]
+	};
+	if (v1.content.kind === "markdown") return {
+		meta: { ...v1.meta },
+		policy: v1.policy,
+		source: {
+			type: "blocknotejs",
+			docJson: v1.content.content ?? v1.content.resourceUri ?? ""
+		},
+		targets: [
+			"markdown",
+			"application/json",
+			"application/xml"
+		]
+	};
+	return {
+		meta: { ...v1.meta },
+		policy: v1.policy,
+		source: {
+			type: "blocknotejs",
+			docJson: {
+				kind: "data",
+				mimeType: v1.content.mimeType,
+				model: "schema"
+			}
+		},
+		targets: ["application/json", "application/xml"]
+	};
+}
+
+//#endregion
+export { toV2FromV1 };

package/dist/presentations.d.ts

@@ -1,6 +1,6 @@
 import { Stability } from "./ownership.js";
 import z from "zod";
-import * as _lssm_lib_schema330 from "@lssm/lib.schema";
+import * as _lssm_lib_schema136 from "@lssm/lib.schema";
 import { AnySchemaModel } from "@lssm/lib.schema";
 
 //#region src/presentations.d.ts
@@ -62,7 +62,7 @@ declare class PresentationRegistry {
 declare function jsonSchemaForPresentation(p: PresentationSpec): {
   framework: "react";
   componentKey: string;
-  props: z.core.ZodStandardJSONSchemaPayload<_lssm_lib_schema330.TopLevelZodFromModel<_lssm_lib_schema330.SchemaModelFieldsAnyConfig<AnySchemaModel | _lssm_lib_schema330.AnyFieldType | _lssm_lib_schema330.AnyEnumType>>>;
+  props: z.core.ZodStandardJSONSchemaPayload<_lssm_lib_schema136.TopLevelZodFromModel<_lssm_lib_schema136.SchemaModelFieldsAnyConfig<AnySchemaModel | _lssm_lib_schema136.AnyFieldType | _lssm_lib_schema136.AnyEnumType>>>;
   meta: {
     readonly name: string;
     readonly version: number;
@@ -84,7 +84,7 @@ declare function jsonSchemaForPresentation(p: PresentationSpec): {
   kind: PresentationKind;
 } | {
   mimeType: string;
-  model: z.core.ZodStandardJSONSchemaPayload<_lssm_lib_schema330.TopLevelZodFromModel<_lssm_lib_schema330.SchemaModelFieldsAnyConfig<AnySchemaModel | _lssm_lib_schema330.AnyFieldType | _lssm_lib_schema330.AnyEnumType>>>;
+  model: z.core.ZodStandardJSONSchemaPayload<_lssm_lib_schema136.TopLevelZodFromModel<_lssm_lib_schema136.SchemaModelFieldsAnyConfig<AnySchemaModel | _lssm_lib_schema136.AnyFieldType | _lssm_lib_schema136.AnyEnumType>>>;
   meta: {
     readonly name: string;
     readonly version: number;

package/dist/presentations.js

@@ -1 +1,66 @@
-import e from"zod";function t(e){return`${e.meta.name}.v${e.meta.version}`}var n=class{items=new Map;constructor(e){e&&e.forEach(e=>this.register(e))}register(e){let n=t(e);if(this.items.has(n))throw Error(`Duplicate presentation ${n}`);return this.items.set(n,e),this}list(){return[...this.items.values()]}get(e,t){if(t!=null)return this.items.get(`${e}.v${t}`);let n,r=-1/0;for(let[t,i]of this.items.entries())t.startsWith(`${e}.v`)&&i.meta.version>r&&(r=i.meta.version,n=i);return n}};function r(t){let n={meta:{name:t.meta.name,version:t.meta.version,stability:t.meta.stability??`stable`,tags:t.meta.tags??[],description:t.meta.description??``},kind:t.content.kind};return t.content.kind===`web_component`?{...n,framework:t.content.framework,componentKey:t.content.componentKey,props:e.toJSONSchema(t.content.props.getZod())}:t.content.kind===`markdown`?{...n,content:t.content.content,resourceUri:t.content.resourceUri}:{...n,mimeType:t.content.mimeType,model:e.toJSONSchema(t.content.model.getZod())}}export{n as PresentationRegistry,r as jsonSchemaForPresentation};
+import z from "zod";
+
+//#region src/presentations.ts
+function keyOf(p) {
+	return `${p.meta.name}.v${p.meta.version}`;
+}
+/** In-memory registry for V1 PresentationSpec. */
+var PresentationRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	constructor(items) {
+		if (items) items.forEach((p) => this.register(p));
+	}
+	register(p) {
+		const key = keyOf(p);
+		if (this.items.has(key)) throw new Error(`Duplicate presentation ${key}`);
+		this.items.set(key, p);
+		return this;
+	}
+	list() {
+		return [...this.items.values()];
+	}
+	get(name, version) {
+		if (version != null) return this.items.get(`${name}.v${version}`);
+		let candidate;
+		let max = -Infinity;
+		for (const [k, p] of this.items.entries()) {
+			if (!k.startsWith(`${name}.v`)) continue;
+			if (p.meta.version > max) {
+				max = p.meta.version;
+				candidate = p;
+			}
+		}
+		return candidate;
+	}
+};
+function jsonSchemaForPresentation(p) {
+	const base = {
+		meta: {
+			name: p.meta.name,
+			version: p.meta.version,
+			stability: p.meta.stability ?? "stable",
+			tags: p.meta.tags ?? [],
+			description: p.meta.description ?? ""
+		},
+		kind: p.content.kind
+	};
+	if (p.content.kind === "web_component") return {
+		...base,
+		framework: p.content.framework,
+		componentKey: p.content.componentKey,
+		props: z.toJSONSchema(p.content.props.getZod())
+	};
+	if (p.content.kind === "markdown") return {
+		...base,
+		content: p.content.content,
+		resourceUri: p.content.resourceUri
+	};
+	return {
+		...base,
+		mimeType: p.content.mimeType,
+		model: z.toJSONSchema(p.content.model.getZod())
+	};
+}
+
+//#endregion
+export { PresentationRegistry, jsonSchemaForPresentation };