@contractspec/lib.contracts 1.50.0 → 1.51.0

package/dist/policy/guards.js

@@ -0,0 +1,254 @@
+import { PolicyViolationError } from "./context.js";
+
+//#region src/policy/guards.ts
+function checkAuthLevel(ctx, required) {
+	if (required === "anonymous") return true;
+	if (required === "user") return ctx.user.id !== "anonymous";
+	if (required === "admin") return ctx.hasRole("admin");
+	return false;
+}
+/**
+* Check if an operation's policy constraints are satisfied.
+*
+* @param ctx - Policy context to check against
+* @param operation - Operation spec to check
+* @param flags - Available feature flags
+* @returns Guard result indicating if operation is allowed
+*
+* @example
+* ```typescript
+* const result = checkPolicyForOperation(ctx, myOperation, ['feature-x']);
+* if (!result.allowed) {
+*   console.log('Denied:', result.reason);
+* }
+* ```
+*/
+function checkPolicyForOperation(ctx, operation, flags = []) {
+	const { policy } = operation;
+	const operationName = `${operation.meta.key}.v${operation.meta.version}`;
+	const missing = {};
+	if (!checkAuthLevel(ctx, policy.auth)) return {
+		allowed: false,
+		reason: `Operation "${operationName}" requires "${policy.auth}" auth level`,
+		missing: { roles: policy.auth === "admin" ? ["admin"] : void 0 }
+	};
+	if (policy.flags?.length) {
+		const availableFlags = new Set(flags);
+		const missingFlags = policy.flags.filter((f) => !availableFlags.has(f));
+		if (missingFlags.length > 0) {
+			missing.flags = missingFlags;
+			return {
+				allowed: false,
+				reason: `Operation "${operationName}" requires feature flags: ${missingFlags.join(", ")}`,
+				missing
+			};
+		}
+	}
+	return { allowed: true };
+}
+/**
+* Assert that an operation's policy constraints are satisfied.
+*
+* @param ctx - Policy context to check against
+* @param operation - Operation spec to check
+* @param flags - Available feature flags
+* @throws {PolicyViolationError} If policy is not satisfied
+*
+* @example
+* ```typescript
+* // Throws if policy not satisfied
+* assertPolicyForOperation(ctx, myOperation);
+*
+* // Safe to proceed with operation
+* await handler(input);
+* ```
+*/
+function assertPolicyForOperation(ctx, operation, flags = []) {
+	const result = checkPolicyForOperation(ctx, operation, flags);
+	if (!result.allowed) {
+		const operationName$1 = `${operation.meta.key}.v${operation.meta.version}`;
+		ctx.auditAccess(operationName$1, "denied", result.reason);
+		throw new PolicyViolationError("access_denied", {
+			operation: operationName$1,
+			reason: result.reason
+		});
+	}
+	const operationName = `${operation.meta.key}.v${operation.meta.version}`;
+	ctx.auditAccess(operationName, "allowed");
+}
+/**
+* Filter operations to only those with satisfied policy constraints.
+*
+* @param ctx - Policy context to check against
+* @param operations - Operations to filter
+* @param flags - Available feature flags
+* @returns Operations that have their policies satisfied
+*/
+function filterOperationsByPolicy(ctx, operations, flags = []) {
+	return operations.filter((op) => checkPolicyForOperation(ctx, op, flags).allowed);
+}
+/**
+* Check if user has the required role for an operation.
+*
+* @param ctx - Policy context to check against
+* @param requiredRole - Role required for the operation
+* @param operation - Optional operation name for error messages
+* @returns Guard result
+*/
+function checkRole(ctx, requiredRole, operation) {
+	if (ctx.hasRole(requiredRole)) return { allowed: true };
+	return {
+		allowed: false,
+		reason: operation ? `Operation "${operation}" requires role "${requiredRole}"` : `Missing required role "${requiredRole}"`,
+		missing: { roles: [requiredRole] }
+	};
+}
+/**
+* Assert user has the required role.
+*
+* @param ctx - Policy context to check against
+* @param requiredRole - Role required
+* @param operation - Optional operation name for error messages
+* @throws {PolicyViolationError} If role is missing
+*/
+function assertRole(ctx, requiredRole, operation) {
+	if (!checkRole(ctx, requiredRole, operation).allowed) throw new PolicyViolationError("missing_role", {
+		operation,
+		requiredRole
+	});
+}
+/**
+* Check if user has any of the required roles.
+*
+* @param ctx - Policy context to check against
+* @param requiredRoles - Any of these roles is sufficient
+* @param operation - Optional operation name for error messages
+* @returns Guard result
+*/
+function checkAnyRole(ctx, requiredRoles, operation) {
+	if (ctx.hasAnyRole(requiredRoles)) return { allowed: true };
+	return {
+		allowed: false,
+		reason: operation ? `Operation "${operation}" requires one of roles: ${requiredRoles.join(", ")}` : `Missing required role (need one of: ${requiredRoles.join(", ")})`,
+		missing: { roles: requiredRoles }
+	};
+}
+/**
+* Check if user has the required permission.
+*
+* @param ctx - Policy context to check against
+* @param requiredPermission - Permission required
+* @param operation - Optional operation name for error messages
+* @returns Guard result
+*/
+function checkPermission(ctx, requiredPermission, operation) {
+	if (ctx.hasPermission(requiredPermission)) return { allowed: true };
+	return {
+		allowed: false,
+		reason: operation ? `Operation "${operation}" requires permission "${requiredPermission}"` : `Missing required permission "${requiredPermission}"`,
+		missing: { permissions: [requiredPermission] }
+	};
+}
+/**
+* Assert user has the required permission.
+*
+* @param ctx - Policy context to check against
+* @param requiredPermission - Permission required
+* @param operation - Optional operation name for error messages
+* @throws {PolicyViolationError} If permission is missing
+*/
+function assertPermission(ctx, requiredPermission, operation) {
+	if (!checkPermission(ctx, requiredPermission, operation).allowed) throw new PolicyViolationError("missing_permission", {
+		operation,
+		requiredPermission
+	});
+}
+/**
+* Check if user has all of the required permissions.
+*
+* @param ctx - Policy context to check against
+* @param requiredPermissions - All of these permissions are required
+* @param operation - Optional operation name for error messages
+* @returns Guard result
+*/
+function checkAllPermissions(ctx, requiredPermissions, operation) {
+	const missing = requiredPermissions.filter((p) => !ctx.hasPermission(p));
+	if (missing.length === 0) return { allowed: true };
+	return {
+		allowed: false,
+		reason: operation ? `Operation "${operation}" requires permissions: ${missing.join(", ")}` : `Missing required permissions: ${missing.join(", ")}`,
+		missing: { permissions: missing }
+	};
+}
+/**
+* Check multiple policy requirements at once.
+*
+* @param ctx - Policy context to check against
+* @param requirements - Combined requirements to check
+* @param flags - Available feature flags
+* @param operation - Optional operation name for error messages
+* @returns Guard result
+*/
+function checkCombinedPolicy(ctx, requirements, flags = [], operation) {
+	const missing = {};
+	const reasons = [];
+	if (requirements.roles?.length) {
+		const missingRoles = requirements.roles.filter((r) => !ctx.hasRole(r));
+		if (missingRoles.length > 0) {
+			missing.roles = missingRoles;
+			reasons.push(`Missing roles: ${missingRoles.join(", ")}`);
+		}
+	}
+	if (requirements.anyRole?.length) {
+		if (!ctx.hasAnyRole(requirements.anyRole)) {
+			missing.roles = [...missing.roles ?? [], ...requirements.anyRole];
+			reasons.push(`Need one of roles: ${requirements.anyRole.join(", ")}`);
+		}
+	}
+	if (requirements.permissions?.length) {
+		const missingPerms = requirements.permissions.filter((p) => !ctx.hasPermission(p));
+		if (missingPerms.length > 0) {
+			missing.permissions = missingPerms;
+			reasons.push(`Missing permissions: ${missingPerms.join(", ")}`);
+		}
+	}
+	if (requirements.anyPermission?.length) {
+		if (!ctx.hasAnyPermission(requirements.anyPermission)) {
+			missing.permissions = [...missing.permissions ?? [], ...requirements.anyPermission];
+			reasons.push(`Need one of permissions: ${requirements.anyPermission.join(", ")}`);
+		}
+	}
+	if (requirements.flags?.length) {
+		const availableFlags = new Set(flags);
+		const missingFlags = requirements.flags.filter((f) => !availableFlags.has(f));
+		if (missingFlags.length > 0) {
+			missing.flags = missingFlags;
+			reasons.push(`Missing feature flags: ${missingFlags.join(", ")}`);
+		}
+	}
+	if (reasons.length > 0) return {
+		allowed: false,
+		reason: (operation ? `Operation "${operation}": ` : "") + reasons.join("; "),
+		missing
+	};
+	return { allowed: true };
+}
+/**
+* Assert multiple policy requirements at once.
+*
+* @param ctx - Policy context to check against
+* @param requirements - Combined requirements to check
+* @param flags - Available feature flags
+* @param operation - Optional operation name for error messages
+* @throws {PolicyViolationError} If any requirement is not met
+*/
+function assertCombinedPolicy(ctx, requirements, flags = [], operation) {
+	const result = checkCombinedPolicy(ctx, requirements, flags, operation);
+	if (!result.allowed) throw new PolicyViolationError("access_denied", {
+		operation,
+		reason: result.reason
+	});
+}
+
+//#endregion
+export { assertCombinedPolicy, assertPermission, assertPolicyForOperation, assertRole, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, filterOperationsByPolicy };

package/dist/policy/index.d.ts

@@ -2,4 +2,15 @@ import { AttributeMatcher, ConsentDefinition, FieldPolicyRule, PIIPolicy, Policy
 import { PolicyRegistry } from "./registry.js";
 import { DecisionContext, PolicyEngine, ResourceContext, SubjectContext, SubjectRelationship } from "./engine.js";
 import { OPAAdapterOptions, OPAClient, OPAEvaluationResult, OPAPolicyAdapter, buildOPAInput } from "./opa-adapter.js";
-export { AttributeMatcher, ConsentDefinition, DecisionContext, FieldPolicyRule, OPAAdapterOptions, OPAClient, OPAEvaluationResult, OPAPolicyAdapter, PIIPolicy, PolicyCondition, PolicyEffect, PolicyEngine, PolicyMeta, PolicyOPAConfig, PolicyRef, PolicyRegistry, PolicyRule, PolicySpec, RateLimitDefinition, RelationshipDefinition, RelationshipMatcher, ResourceContext, ResourceMatcher, SubjectContext, SubjectMatcher, SubjectRelationship, buildOPAInput };
+import { AuditEntry, AuditHandler, PolicyContext, PolicyContextOptions, PolicyUser, PolicyViolationDetails, PolicyViolationError, PolicyViolationType, RateLimitResult, RateLimitState, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext } from "./context.js";
+import { CombinedPolicyRequirements, PolicyGuardResult, assertCombinedPolicy, assertPermission, assertPolicyForOperation, assertRole, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, filterOperationsByPolicy } from "./guards.js";
+import { PolicyConsistencyDeps, PolicyValidationError, PolicyValidationIssue, PolicyValidationLevel, PolicyValidationResult, assertPolicyConsistency, assertPolicySpecValid, validatePolicyConsistency, validatePolicySpec } from "./validation.js";
+
+//#region src/policy/index.d.ts
+
+/**
+ * Helper to define a Policy.
+ */
+declare const definePolicy: (spec: PolicySpec) => PolicySpec;
+//#endregion
+export { AttributeMatcher, AuditEntry, AuditHandler, CombinedPolicyRequirements, ConsentDefinition, DecisionContext, FieldPolicyRule, OPAAdapterOptions, OPAClient, OPAEvaluationResult, OPAPolicyAdapter, PIIPolicy, PolicyCondition, PolicyConsistencyDeps, PolicyContext, PolicyContextOptions, PolicyEffect, PolicyEngine, PolicyGuardResult, PolicyMeta, PolicyOPAConfig, PolicyRef, PolicyRegistry, PolicyRule, PolicySpec, PolicyUser, PolicyValidationError, PolicyValidationIssue, PolicyValidationLevel, PolicyValidationResult, PolicyViolationDetails, PolicyViolationError, PolicyViolationType, RateLimitDefinition, RateLimitResult, RateLimitState, RelationshipDefinition, RelationshipMatcher, ResourceContext, ResourceMatcher, SubjectContext, SubjectMatcher, SubjectRelationship, assertCombinedPolicy, assertPermission, assertPolicyConsistency, assertPolicyForOperation, assertPolicySpecValid, assertRole, buildOPAInput, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext, definePolicy, filterOperationsByPolicy, validatePolicyConsistency, validatePolicySpec };

package/dist/policy/index.js

@@ -1,5 +1,15 @@
 import { PolicyRegistry } from "./registry.js";
 import { PolicyEngine } from "./engine.js";
 import { OPAPolicyAdapter, buildOPAInput } from "./opa-adapter.js";
+import { PolicyViolationError, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext } from "./context.js";
+import { assertCombinedPolicy, assertPermission, assertPolicyForOperation, assertRole, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, filterOperationsByPolicy } from "./guards.js";
+import { PolicyValidationError, assertPolicyConsistency, assertPolicySpecValid, validatePolicyConsistency, validatePolicySpec } from "./validation.js";
 
-export { OPAPolicyAdapter, PolicyEngine, PolicyRegistry, buildOPAInput };
+//#region src/policy/index.ts
+/**
+* Helper to define a Policy.
+*/
+const definePolicy = (spec) => spec;
+
+//#endregion
+export { OPAPolicyAdapter, PolicyEngine, PolicyRegistry, PolicyValidationError, PolicyViolationError, assertCombinedPolicy, assertPermission, assertPolicyConsistency, assertPolicyForOperation, assertPolicySpecValid, assertRole, buildOPAInput, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext, definePolicy, filterOperationsByPolicy, validatePolicyConsistency, validatePolicySpec };

package/dist/policy/spec.d.ts

@@ -1,5 +1,5 @@
-import { OwnerShipMeta } from "../ownership.js";
 import { VersionedSpecRef } from "../versioning/refs.js";
+import { OwnerShipMeta } from "../ownership.js";
 
 //#region src/policy/spec.d.ts
 /** Effect of a policy rule: allow or deny access. */

package/dist/policy/validation.d.ts

@@ -0,0 +1,67 @@
+import { PolicySpec } from "./spec.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
+import { PolicyRegistry } from "./registry.js";
+
+//#region src/policy/validation.d.ts
+
+type PolicyValidationLevel = 'error' | 'warning' | 'info';
+interface PolicyValidationIssue {
+  level: PolicyValidationLevel;
+  message: string;
+  path?: string;
+  context?: Record<string, unknown>;
+}
+interface PolicyValidationResult {
+  valid: boolean;
+  issues: PolicyValidationIssue[];
+}
+/**
+ * Validate a policy spec for internal consistency.
+ *
+ * @param spec - Policy spec to validate
+ * @returns Validation result with any issues found
+ *
+ * @example
+ * ```typescript
+ * const result = validatePolicySpec(myPolicy);
+ * if (!result.valid) {
+ *   console.log('Issues:', result.issues);
+ * }
+ * ```
+ */
+declare function validatePolicySpec(spec: PolicySpec): PolicyValidationResult;
+interface PolicyConsistencyDeps {
+  policies: PolicyRegistry;
+  operations?: OperationSpecRegistry;
+}
+/**
+ * Validate policy consistency across registries.
+ *
+ * Checks that:
+ * - Operations reference valid policies
+ * - Policy actions align with operation kinds
+ *
+ * @param deps - Registry dependencies
+ * @returns Validation result
+ */
+declare function validatePolicyConsistency(deps: PolicyConsistencyDeps): PolicyValidationResult;
+declare class PolicyValidationError extends Error {
+  readonly issues: PolicyValidationIssue[];
+  constructor(message: string, issues: PolicyValidationIssue[]);
+}
+/**
+ * Assert that a policy spec is valid, throwing if not.
+ *
+ * @param spec - Policy spec to validate
+ * @throws {PolicyValidationError} If validation fails
+ */
+declare function assertPolicySpecValid(spec: PolicySpec): void;
+/**
+ * Assert policy consistency across registries.
+ *
+ * @param deps - Registry dependencies
+ * @throws {PolicyValidationError} If validation fails
+ */
+declare function assertPolicyConsistency(deps: PolicyConsistencyDeps): void;
+//#endregion
+export { PolicyConsistencyDeps, PolicyValidationError, PolicyValidationIssue, PolicyValidationLevel, PolicyValidationResult, assertPolicyConsistency, assertPolicySpecValid, validatePolicyConsistency, validatePolicySpec };

package/dist/policy/validation.js

@@ -0,0 +1,307 @@
+//#region src/policy/validation.ts
+/**
+* Validate a policy spec for internal consistency.
+*
+* @param spec - Policy spec to validate
+* @returns Validation result with any issues found
+*
+* @example
+* ```typescript
+* const result = validatePolicySpec(myPolicy);
+* if (!result.valid) {
+*   console.log('Issues:', result.issues);
+* }
+* ```
+*/
+function validatePolicySpec(spec) {
+	const issues = [];
+	validateMeta(spec, issues);
+	validateRules(spec, issues);
+	validateFieldPolicies(spec, issues);
+	validateRateLimits(spec, issues);
+	validateConsents(spec, issues);
+	validateRelationships(spec, issues);
+	return {
+		valid: issues.filter((i) => i.level === "error").length === 0,
+		issues
+	};
+}
+function validateMeta(spec, issues) {
+	const { meta } = spec;
+	if (!meta.key?.trim()) issues.push({
+		level: "error",
+		message: "Policy must have a non-empty key",
+		path: "meta.key"
+	});
+	if (!meta.version?.trim()) issues.push({
+		level: "error",
+		message: "Policy must have a non-empty version",
+		path: "meta.version"
+	});
+	if (!meta.owners?.length) issues.push({
+		level: "warning",
+		message: "Policy should specify owners",
+		path: "meta.owners"
+	});
+}
+function validateRules(spec, issues) {
+	if (!spec.rules?.length) {
+		issues.push({
+			level: "warning",
+			message: "Policy has no rules defined",
+			path: "rules"
+		});
+		return;
+	}
+	const seenRateRefs = /* @__PURE__ */ new Set();
+	spec.rules.forEach((rule, index) => {
+		const path = `rules[${index}]`;
+		if (!rule.actions?.length) issues.push({
+			level: "error",
+			message: "Rule must specify at least one action",
+			path: `${path}.actions`
+		});
+		if (!["allow", "deny"].includes(rule.effect)) issues.push({
+			level: "error",
+			message: `Invalid rule effect: ${rule.effect}`,
+			path: `${path}.effect`
+		});
+		if (typeof rule.rateLimit === "string") {
+			seenRateRefs.add(rule.rateLimit);
+			if (!spec.rateLimits?.some((rl) => rl.id === rule.rateLimit)) issues.push({
+				level: "error",
+				message: `Rate limit "${rule.rateLimit}" referenced but not defined`,
+				path: `${path}.rateLimit`
+			});
+		}
+		if (rule.requiresConsent?.length) {
+			for (const consentId of rule.requiresConsent) if (!spec.consents?.some((c) => c.id === consentId)) issues.push({
+				level: "error",
+				message: `Consent "${consentId}" referenced but not defined`,
+				path: `${path}.requiresConsent`
+			});
+		}
+		validateConditions(rule.conditions, `${path}.conditions`, issues);
+	});
+	if (spec.rateLimits?.length) {
+		for (const rl of spec.rateLimits) if (!seenRateRefs.has(rl.id)) {
+			if (!spec.rules.some((r) => typeof r.rateLimit === "object" && r.rateLimit.id === rl.id)) issues.push({
+				level: "info",
+				message: `Rate limit "${rl.id}" is defined but not referenced`,
+				path: `rateLimits`
+			});
+		}
+	}
+}
+function validateFieldPolicies(spec, issues) {
+	if (!spec.fieldPolicies?.length) return;
+	const seenFields = /* @__PURE__ */ new Map();
+	spec.fieldPolicies.forEach((rule, index) => {
+		const path = `fieldPolicies[${index}]`;
+		if (!rule.field?.trim()) issues.push({
+			level: "error",
+			message: "Field policy must specify a field",
+			path: `${path}.field`
+		});
+		if (!rule.actions?.length) issues.push({
+			level: "error",
+			message: "Field policy must specify at least one action",
+			path: `${path}.actions`
+		});
+		for (const action of rule.actions) if (!["read", "write"].includes(action)) issues.push({
+			level: "error",
+			message: `Invalid field action: ${action}`,
+			path: `${path}.actions`
+		});
+		const existing = seenFields.get(rule.field) ?? [];
+		existing.push(rule);
+		seenFields.set(rule.field, existing);
+		validateConditions(rule.conditions, `${path}.conditions`, issues);
+	});
+	for (const [field, rules] of seenFields.entries()) if (rules.length > 1) {
+		if (rules.some((r) => r.effect === "allow") && rules.some((r) => r.effect === "deny")) issues.push({
+			level: "warning",
+			message: `Field "${field}" has potentially conflicting allow/deny policies`,
+			path: "fieldPolicies",
+			context: {
+				field,
+				ruleCount: rules.length
+			}
+		});
+	}
+}
+function validateRateLimits(spec, issues) {
+	if (!spec.rateLimits?.length) return;
+	const seenIds = /* @__PURE__ */ new Set();
+	spec.rateLimits.forEach((rl, index) => {
+		const path = `rateLimits[${index}]`;
+		if (!rl.id?.trim()) issues.push({
+			level: "error",
+			message: "Rate limit must have an id",
+			path: `${path}.id`
+		});
+		else if (seenIds.has(rl.id)) issues.push({
+			level: "error",
+			message: `Duplicate rate limit id: ${rl.id}`,
+			path: `${path}.id`
+		});
+		else seenIds.add(rl.id);
+		if (typeof rl.rpm !== "number" || rl.rpm <= 0) issues.push({
+			level: "error",
+			message: "Rate limit rpm must be a positive number",
+			path: `${path}.rpm`
+		});
+		if (rl.windowSeconds !== void 0 && rl.windowSeconds <= 0) issues.push({
+			level: "error",
+			message: "Rate limit windowSeconds must be positive if specified",
+			path: `${path}.windowSeconds`
+		});
+		if (rl.burst !== void 0 && rl.burst < 0) issues.push({
+			level: "error",
+			message: "Rate limit burst must be non-negative if specified",
+			path: `${path}.burst`
+		});
+	});
+}
+function validateConsents(spec, issues) {
+	if (!spec.consents?.length) return;
+	const seenIds = /* @__PURE__ */ new Set();
+	spec.consents.forEach((consent, index) => {
+		const path = `consents[${index}]`;
+		if (!consent.id?.trim()) issues.push({
+			level: "error",
+			message: "Consent must have an id",
+			path: `${path}.id`
+		});
+		else if (seenIds.has(consent.id)) issues.push({
+			level: "error",
+			message: `Duplicate consent id: ${consent.id}`,
+			path: `${path}.id`
+		});
+		else seenIds.add(consent.id);
+		if (!consent.scope?.trim()) issues.push({
+			level: "error",
+			message: "Consent must specify a scope",
+			path: `${path}.scope`
+		});
+		if (!consent.purpose?.trim()) issues.push({
+			level: "error",
+			message: "Consent must specify a purpose",
+			path: `${path}.purpose`
+		});
+		if (consent.expiresInDays !== void 0 && consent.expiresInDays <= 0) issues.push({
+			level: "error",
+			message: "Consent expiresInDays must be positive if specified",
+			path: `${path}.expiresInDays`
+		});
+	});
+}
+function validateRelationships(spec, issues) {
+	if (!spec.relationships?.length) return;
+	const seenRelations = /* @__PURE__ */ new Set();
+	spec.relationships.forEach((rel, index) => {
+		const path = `relationships[${index}]`;
+		const key = `${rel.subjectType}:${rel.relation}:${rel.objectType}`;
+		if (!rel.subjectType?.trim()) issues.push({
+			level: "error",
+			message: "Relationship must specify subjectType",
+			path: `${path}.subjectType`
+		});
+		if (!rel.relation?.trim()) issues.push({
+			level: "error",
+			message: "Relationship must specify relation",
+			path: `${path}.relation`
+		});
+		if (!rel.objectType?.trim()) issues.push({
+			level: "error",
+			message: "Relationship must specify objectType",
+			path: `${path}.objectType`
+		});
+		if (seenRelations.has(key)) issues.push({
+			level: "warning",
+			message: `Duplicate relationship definition: ${key}`,
+			path
+		});
+		else seenRelations.add(key);
+	});
+}
+function validateConditions(conditions, path, issues) {
+	if (!conditions?.length) return;
+	conditions.forEach((cond, index) => {
+		if (!cond.expression?.trim()) issues.push({
+			level: "error",
+			message: "Condition must have a non-empty expression",
+			path: `${path}[${index}].expression`
+		});
+	});
+}
+/**
+* Validate policy consistency across registries.
+*
+* Checks that:
+* - Operations reference valid policies
+* - Policy actions align with operation kinds
+*
+* @param deps - Registry dependencies
+* @returns Validation result
+*/
+function validatePolicyConsistency(deps) {
+	const issues = [];
+	for (const policy of deps.policies.list()) {
+		const specResult = validatePolicySpec(policy);
+		issues.push(...specResult.issues.map((i) => ({
+			...i,
+			path: `${policy.meta.key}.v${policy.meta.version}${i.path ? `.${i.path}` : ""}`
+		})));
+	}
+	if (deps.operations) for (const operation of deps.operations.list()) {
+		const policyRefs = operation.policy.policies ?? [];
+		for (const ref of policyRefs) if (!deps.policies.get(ref.key, ref.version)) issues.push({
+			level: "error",
+			message: `Operation "${operation.meta.key}.v${operation.meta.version}" references unknown policy "${ref.key}.v${ref.version}"`,
+			path: `operations.${operation.meta.key}.policy.policies`
+		});
+		const fieldPolicies = operation.policy.fieldPolicies ?? [];
+		for (const fp of fieldPolicies) if (fp.policy) {
+			if (!deps.policies.get(fp.policy.key, fp.policy.version)) issues.push({
+				level: "error",
+				message: `Operation "${operation.meta.key}.v${operation.meta.version}" references unknown field policy "${fp.policy.key}.v${fp.policy.version}"`,
+				path: `operations.${operation.meta.key}.policy.fieldPolicies`
+			});
+		}
+	}
+	return {
+		valid: issues.filter((i) => i.level === "error").length === 0,
+		issues
+	};
+}
+var PolicyValidationError = class extends Error {
+	constructor(message, issues) {
+		super(message);
+		this.issues = issues;
+		this.name = "PolicyValidationError";
+	}
+};
+/**
+* Assert that a policy spec is valid, throwing if not.
+*
+* @param spec - Policy spec to validate
+* @throws {PolicyValidationError} If validation fails
+*/
+function assertPolicySpecValid(spec) {
+	const result = validatePolicySpec(spec);
+	if (!result.valid) throw new PolicyValidationError(`Policy ${spec.meta.key}.v${spec.meta.version} is invalid`, result.issues);
+}
+/**
+* Assert policy consistency across registries.
+*
+* @param deps - Registry dependencies
+* @throws {PolicyValidationError} If validation fails
+*/
+function assertPolicyConsistency(deps) {
+	const result = validatePolicyConsistency(deps);
+	if (!result.valid) throw new PolicyValidationError("Policy consistency check failed", result.issues);
+}
+
+//#endregion
+export { PolicyValidationError, assertPolicyConsistency, assertPolicySpecValid, validatePolicyConsistency, validatePolicySpec };

package/dist/presentations/presentations.d.ts

@@ -1,3 +1,4 @@
+import { CapabilityRef } from "../capabilities/capabilities.js";
 import { OwnerShipMeta } from "../ownership.js";
 import { AnySchemaModel } from "@contractspec/lib.schema";
 import { BlockConfig } from "@blocknote/core";
@@ -38,6 +39,11 @@ type PresentationSource = PresentationSourceComponentReact | PresentationSourceB
  */
 interface PresentationSpec {
   meta: PresentationSpecMeta;
+  /**
+   * Optional reference to the capability that provides this presentation.
+   * Used for bidirectional linking between capabilities and presentations.
+   */
+  capability?: CapabilityRef;
   policy?: {
     flags?: string[];
     pii?: string[];