@contractspec/lib.contracts 1.49.0 → 1.51.0

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[];

package/dist/tests/spec.d.ts

@@ -1,14 +1,18 @@
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 import { OwnerShipMeta } from "../ownership.js";
 
 //#region src/tests/spec.d.ts
-interface OperationTargetRef {
-  key: string;
-  version?: string;
-}
-interface WorkflowTargetRef {
-  key: string;
-  version?: string;
-}
+
+/**
+ * Reference to an operation to be tested.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type OperationTargetRef = OptionalVersionedSpecRef;
+/**
+ * Reference to a workflow to be tested.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type WorkflowTargetRef = OptionalVersionedSpecRef;
 type TestTarget = {
   type: 'operation';
   operation: OperationTargetRef;
@@ -66,10 +70,11 @@ interface TestSpec {
   scenarios: TestScenario[];
   coverage?: CoverageRequirement;
 }
-interface TestSpecRef {
-  key: string;
-  version?: string;
-}
+/**
+ * Reference to a test spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type TestSpecRef = OptionalVersionedSpecRef;
 declare class TestRegistry {
   private readonly items;
   register(spec: TestSpec): this;

package/dist/themes.d.ts

@@ -1,7 +1,9 @@
+import { VersionedSpecRef } from "./versioning/refs.js";
 import { OwnerShipMeta } from "./ownership.js";
 import { SpecContractRegistry } from "./registry.js";
 
 //#region src/themes.d.ts
+/** Scope at which a theme can be applied. */
 type ThemeScope = 'global' | 'tenant' | 'user';
 interface ThemeToken<T> {
   value: T;
@@ -39,10 +41,11 @@ interface ThemeSpec {
   components?: ComponentVariantSpec[];
   overrides?: ThemeOverride[];
 }
-interface ThemeRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a theme spec.
+ * Uses key and version to identify a specific theme.
+ */
+type ThemeRef = VersionedSpecRef;
 declare class ThemeRegistry extends SpecContractRegistry<'theme', ThemeSpec> {
   constructor(items?: ThemeSpec[]);
 }

package/dist/translations/index.d.ts

@@ -0,0 +1,6 @@
+import { BlueprintTranslationCatalog, PlatformTranslationCatalog, TranslationCatalogMeta, TranslationEntry } from "./catalog.js";
+import { TenantTranslationOverride } from "./tenant.js";
+import { Locale, MessageKey, MessageVariant, PlaceholderDef, PlaceholderType, PluralCategory, PluralRule, PluralRuleSet, TranslationMessage, TranslationMessages, TranslationMeta, TranslationRef, TranslationSpec, VariantType, defineTranslation } from "./spec.js";
+import { TranslationLookupResult, TranslationRegistry, TranslationRegistryStats } from "./registry.js";
+import { ICUValidationResult, MissingTranslation, TranslationValidationError, TranslationValidationIssue, TranslationValidationLevel, TranslationValidationResult, assertTranslationSpecValid, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec } from "./validation.js";
+export { type BlueprintTranslationCatalog, ICUValidationResult, Locale, MessageKey, MessageVariant, MissingTranslation, PlaceholderDef, PlaceholderType, type PlatformTranslationCatalog, PluralCategory, PluralRule, PluralRuleSet, TenantTranslationOverride, type TranslationCatalogMeta, type TranslationEntry, TranslationLookupResult, TranslationMessage, TranslationMessages, TranslationMeta, TranslationRef, TranslationRegistry, TranslationRegistryStats, TranslationSpec, TranslationValidationError, TranslationValidationIssue, TranslationValidationLevel, TranslationValidationResult, VariantType, assertTranslationSpecValid, defineTranslation, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec };

package/dist/translations/index.js

@@ -0,0 +1,5 @@
+import { defineTranslation } from "./spec.js";
+import { TranslationRegistry } from "./registry.js";
+import { TranslationValidationError, assertTranslationSpecValid, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec } from "./validation.js";
+
+export { TranslationRegistry, TranslationValidationError, assertTranslationSpecValid, defineTranslation, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec };

package/dist/translations/registry.d.ts

@@ -0,0 +1,144 @@
+import { Locale, MessageKey, TranslationMessage, TranslationSpec } from "./spec.js";
+
+//#region src/translations/registry.d.ts
+
+interface TranslationLookupResult {
+  spec: TranslationSpec;
+  message: TranslationMessage;
+  locale: Locale;
+  fromFallback: boolean;
+}
+interface TranslationRegistryStats {
+  totalSpecs: number;
+  locales: Locale[];
+  domains: string[];
+  totalMessages: number;
+}
+/**
+ * Registry for translation specs with locale-aware lookup.
+ */
+declare class TranslationRegistry {
+  private readonly specs;
+  private readonly latestByLocale;
+  private readonly locales;
+  private readonly domains;
+  constructor(items?: TranslationSpec[]);
+  /**
+   * Register a translation spec.
+   *
+   * @param spec - Translation spec to register
+   */
+  register(spec: TranslationSpec): void;
+  /**
+   * Get a translation spec by key, version, and locale.
+   *
+   * @param key - Translation spec key
+   * @param version - Version string
+   * @param locale - Locale code
+   * @returns Translation spec or undefined
+   */
+  get(key: string, version: string, locale: Locale): TranslationSpec | undefined;
+  /**
+   * Get the latest version of a translation spec for a locale.
+   *
+   * @param key - Translation spec key
+   * @param locale - Locale code
+   * @returns Translation spec or undefined
+   */
+  getLatest(key: string, locale: Locale): TranslationSpec | undefined;
+  /**
+   * Get a specific message from a translation spec.
+   *
+   * @param specKey - Translation spec key
+   * @param messageKey - Message key within the spec
+   * @param locale - Locale code
+   * @param version - Optional version (uses latest if not specified)
+   * @returns Translation message or undefined
+   */
+  getMessage(specKey: string, messageKey: MessageKey, locale: Locale, version?: string): TranslationMessage | undefined;
+  /**
+   * Get a message value with fallback chain support.
+   *
+   * @param specKey - Translation spec key
+   * @param messageKey - Message key within the spec
+   * @param locale - Primary locale
+   * @param fallbackLocale - Fallback locale (optional, uses spec's fallback if not provided)
+   * @param version - Optional version (uses latest if not specified)
+   * @returns Translation lookup result or undefined
+   */
+  getWithFallback(specKey: string, messageKey: MessageKey, locale: Locale, fallbackLocale?: Locale, version?: string): TranslationLookupResult | undefined;
+  /**
+   * Get a message value string with fallback.
+   *
+   * Convenience method that returns just the string value or a fallback.
+   *
+   * @param specKey - Translation spec key
+   * @param messageKey - Message key
+   * @param locale - Primary locale
+   * @param fallback - String to return if message not found (default: messageKey)
+   * @returns Message value or fallback
+   */
+  getValue(specKey: string, messageKey: MessageKey, locale: Locale, fallback?: string): string;
+  /**
+   * List all locales available for a spec key.
+   *
+   * @param specKey - Translation spec key
+   * @returns Array of available locales
+   */
+  listLocales(specKey: string): Locale[];
+  /**
+   * List all translation specs.
+   *
+   * @returns Array of all registered translation specs
+   */
+  list(): TranslationSpec[];
+  /**
+   * List translation specs by locale.
+   *
+   * @param locale - Locale to filter by
+   * @returns Array of translation specs for the locale
+   */
+  listByLocale(locale: Locale): TranslationSpec[];
+  /**
+   * List translation specs by domain.
+   *
+   * @param domain - Domain to filter by
+   * @returns Array of translation specs for the domain
+   */
+  listByDomain(domain: string): TranslationSpec[];
+  /**
+   * Check if a translation spec exists.
+   *
+   * @param key - Translation spec key
+   * @param locale - Locale code
+   * @param version - Optional version
+   * @returns True if spec exists
+   */
+  has(key: string, locale: Locale, version?: string): boolean;
+  /**
+   * Get all registered locales.
+   *
+   * @returns Set of all registered locales
+   */
+  getLocales(): ReadonlySet<Locale>;
+  /**
+   * Get all registered domains.
+   *
+   * @returns Set of all registered domains
+   */
+  getDomains(): ReadonlySet<string>;
+  /**
+   * Get registry statistics.
+   *
+   * @returns Registry statistics
+   */
+  getStats(): TranslationRegistryStats;
+  /**
+   * Clear all registered specs.
+   */
+  clear(): void;
+  private makeKey;
+  private isNewerVersion;
+}
+//#endregion
+export { TranslationLookupResult, TranslationRegistry, TranslationRegistryStats };