@contractspec/lib.contracts 0.0.0-canary-20260119225944 → 0.0.0-canary-20260202053150

package/dist/serialization/types.d.ts

@@ -0,0 +1,103 @@
+//#region src/serialization/types.d.ts
+/**
+ * Serialized types for Server -> Client Component transfer.
+ *
+ * These are plain JSON-serializable versions of spec types that can be
+ * safely passed from Server Components to Client Components in Next.js.
+ */
+/** Serialized schema model that can be passed to client components */
+interface SerializedSchemaModel {
+  name: string;
+  description?: string | null;
+  fields: Record<string, SerializedFieldConfig>;
+}
+interface SerializedFieldConfig {
+  typeName: string;
+  isOptional: boolean;
+  isArray?: boolean;
+}
+/** Serialized operation spec for client components */
+interface SerializedOperationSpec {
+  meta: {
+    key: string;
+    version: string;
+    stability?: string;
+    owners?: string[];
+    tags?: string[];
+    description?: string;
+    goal?: string;
+    context?: string;
+  };
+  io: {
+    input: SerializedSchemaModel | null;
+    output: SerializedSchemaModel | null;
+  };
+  policy?: {
+    auth?: string;
+  };
+}
+/** Serialized event spec for client components */
+interface SerializedEventSpec {
+  meta: {
+    key: string;
+    version: string;
+    stability?: string;
+    owners?: string[];
+    tags?: string[];
+    description?: string;
+  };
+  payload: SerializedSchemaModel | null;
+}
+/** Serialized presentation spec for client components */
+interface SerializedPresentationSpec {
+  meta: {
+    key: string;
+    version: string;
+    stability?: string;
+    owners?: string[];
+    tags?: string[];
+    description?: string;
+    goal?: string;
+    context?: string;
+  };
+  source: {
+    type: string;
+    framework?: string;
+    componentKey?: string;
+  };
+  targets?: string[];
+}
+/** Serialized data view spec for client components */
+interface SerializedDataViewSpec {
+  meta: {
+    key: string;
+    version: string;
+    stability?: string;
+    owners?: string[];
+    tags?: string[];
+    description?: string;
+    title?: string;
+  };
+  /** Serialized source configuration */
+  source?: unknown;
+  /** Serialized view configuration */
+  view?: unknown;
+}
+/** Serialized form spec for client components */
+interface SerializedFormSpec {
+  meta: {
+    key: string;
+    version?: string;
+    stability?: string;
+    owners?: string[];
+    tags?: string[];
+    description?: string;
+    title?: string;
+  };
+  /** Serialized form fields (passed through for display) */
+  fields?: unknown;
+  /** Serialized form actions (passed through for display) */
+  actions?: unknown;
+}
+//#endregion
+export { SerializedDataViewSpec, SerializedEventSpec, SerializedFieldConfig, SerializedFormSpec, SerializedOperationSpec, SerializedPresentationSpec, SerializedSchemaModel };

package/dist/server/rest-elysia.d.ts

@@ -1,5 +1,5 @@
-import { OperationSpecRegistry } from "../operations/registry.js";
 import { HandlerCtx } from "../types.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
 import { RestOptions } from "./rest-generic.js";
 import { Elysia } from "elysia";
 

package/dist/server/rest-express.d.ts

@@ -1,5 +1,5 @@
-import { OperationSpecRegistry } from "../operations/registry.js";
 import { HandlerCtx } from "../types.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
 import { RestOptions } from "./rest-generic.js";
 import { Request, Router } from "express";
 

package/dist/server/rest-generic.d.ts

@@ -1,5 +1,5 @@
-import { OperationSpecRegistry } from "../operations/registry.js";
 import { HandlerCtx } from "../types.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
 
 //#region src/server/rest-generic.d.ts
 interface RestOptions {

package/dist/server/rest-next-app.d.ts

@@ -1,5 +1,5 @@
-import { OperationSpecRegistry } from "../operations/registry.js";
 import { HandlerCtx } from "../types.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
 import { RestOptions } from "./rest-generic.js";
 
 //#region src/server/rest-next-app.d.ts

package/dist/server/rest-next-mcp.d.ts

@@ -1,5 +1,5 @@
-import { OperationSpecRegistry } from "../operations/registry.js";
 import { HandlerCtx } from "../types.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
 
 //#region src/server/rest-next-mcp.d.ts
 declare function makeNextMcpServerFromRegistry(reg: OperationSpecRegistry, ctxFactory: () => HandlerCtx): {

package/dist/server/rest-next-pages.d.ts

@@ -1,5 +1,5 @@
-import { OperationSpecRegistry } from "../operations/registry.js";
 import { HandlerCtx } from "../types.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
 import { RestOptions } from "./rest-generic.js";
 import { NextApiRequest, NextApiResponse } from "next";
 

package/dist/telemetry/spec.d.ts

@@ -1,5 +1,5 @@
-import { OwnerShipMeta } from "../ownership.js";
 import { SpecContractRegistry } from "../registry.js";
+import { OwnerShipMeta } from "../ownership.js";
 
 //#region src/telemetry/spec.d.ts
 type TelemetryPrivacyLevel = 'public' | 'internal' | 'pii' | 'sensitive';

package/dist/telemetry/tracker.d.ts

@@ -1,5 +1,6 @@
 import { TelemetryEventDef, TelemetryRegistry, TelemetrySpec } from "./spec.js";
 import { TelemetryAnomalyMonitor } from "./anomaly.js";
+import { Actor, Channel } from "../types.js";
 
 //#region src/telemetry/tracker.d.ts
 interface TelemetryEventContext {
@@ -7,8 +8,8 @@ interface TelemetryEventContext {
   organizationId?: string | null;
   userId?: string | null;
   sessionId?: string | null;
-  actor?: 'anonymous' | 'user' | 'admin';
-  channel?: 'web' | 'mobile' | 'job' | 'agent';
+  actor?: Actor;
+  channel?: Channel;
   metadata?: Record<string, unknown>;
 }
 interface TelemetryDispatch {

package/dist/tests/runner.d.ts

@@ -1,6 +1,6 @@
 import { Assertion, TestScenario, TestSpec } from "./spec.js";
-import { OperationSpecRegistry } from "../operations/registry.js";
 import { HandlerCtx } from "../types.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
 import "../index.js";
 
 //#region src/tests/runner.d.ts

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 { OwnerShipMeta } from "./ownership.js";
+import { VersionedSpecRef } from "./versioning/refs.js";
 import { SpecContractRegistry } from "./registry.js";
+import { OwnerShipMeta } from "./ownership.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 };

package/dist/translations/registry.js

@@ -0,0 +1,223 @@
+//#region src/translations/registry.ts
+/**
+* Registry for translation specs with locale-aware lookup.
+*/
+var TranslationRegistry = class {
+	specs = /* @__PURE__ */ new Map();
+	latestByLocale = /* @__PURE__ */ new Map();
+	locales = /* @__PURE__ */ new Set();
+	domains = /* @__PURE__ */ new Set();
+	constructor(items) {
+		if (items) for (const spec of items) this.register(spec);
+	}
+	/**
+	* Register a translation spec.
+	*
+	* @param spec - Translation spec to register
+	*/
+	register(spec) {
+		const fullKey = this.makeKey(spec.meta.key, spec.meta.version, spec.locale);
+		this.specs.set(fullKey, spec);
+		const localeKey = `${spec.meta.key}:${spec.locale}`;
+		const existing = this.latestByLocale.get(localeKey);
+		if (!existing || this.isNewerVersion(spec.meta.version, existing.meta.version)) this.latestByLocale.set(localeKey, spec);
+		this.locales.add(spec.locale);
+		this.domains.add(spec.meta.domain);
+	}
+	/**
+	* 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, version, locale) {
+		return this.specs.get(this.makeKey(key, version, locale));
+	}
+	/**
+	* 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, locale) {
+		return this.latestByLocale.get(`${key}:${locale}`);
+	}
+	/**
+	* 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, messageKey, locale, version) {
+		const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+		if (!spec) return void 0;
+		return spec.messages[messageKey];
+	}
+	/**
+	* 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, messageKey, locale, fallbackLocale, version) {
+		const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+		if (spec) {
+			const message = spec.messages[messageKey];
+			if (message) return {
+				spec,
+				message,
+				locale,
+				fromFallback: false
+			};
+			fallbackLocale = fallbackLocale ?? spec.fallback;
+		}
+		if (fallbackLocale && fallbackLocale !== locale) {
+			const fallbackSpec = version ? this.get(specKey, version, fallbackLocale) : this.getLatest(specKey, fallbackLocale);
+			if (fallbackSpec) {
+				const message = fallbackSpec.messages[messageKey];
+				if (message) return {
+					spec: fallbackSpec,
+					message,
+					locale: fallbackLocale,
+					fromFallback: true
+				};
+			}
+		}
+	}
+	/**
+	* 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, messageKey, locale, fallback) {
+		return this.getWithFallback(specKey, messageKey, locale)?.message.value ?? fallback ?? messageKey;
+	}
+	/**
+	* List all locales available for a spec key.
+	*
+	* @param specKey - Translation spec key
+	* @returns Array of available locales
+	*/
+	listLocales(specKey) {
+		const locales = [];
+		for (const [key, spec] of this.specs.entries()) if (key.startsWith(`${specKey}:`)) {
+			if (!locales.includes(spec.locale)) locales.push(spec.locale);
+		}
+		return locales;
+	}
+	/**
+	* List all translation specs.
+	*
+	* @returns Array of all registered translation specs
+	*/
+	list() {
+		return [...this.specs.values()];
+	}
+	/**
+	* List translation specs by locale.
+	*
+	* @param locale - Locale to filter by
+	* @returns Array of translation specs for the locale
+	*/
+	listByLocale(locale) {
+		return [...this.specs.values()].filter((s) => s.locale === locale);
+	}
+	/**
+	* List translation specs by domain.
+	*
+	* @param domain - Domain to filter by
+	* @returns Array of translation specs for the domain
+	*/
+	listByDomain(domain) {
+		return [...this.specs.values()].filter((s) => s.meta.domain === domain);
+	}
+	/**
+	* 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, locale, version) {
+		if (version) return this.specs.has(this.makeKey(key, version, locale));
+		return this.latestByLocale.has(`${key}:${locale}`);
+	}
+	/**
+	* Get all registered locales.
+	*
+	* @returns Set of all registered locales
+	*/
+	getLocales() {
+		return this.locales;
+	}
+	/**
+	* Get all registered domains.
+	*
+	* @returns Set of all registered domains
+	*/
+	getDomains() {
+		return this.domains;
+	}
+	/**
+	* Get registry statistics.
+	*
+	* @returns Registry statistics
+	*/
+	getStats() {
+		let totalMessages = 0;
+		for (const spec of this.specs.values()) totalMessages += Object.keys(spec.messages).length;
+		return {
+			totalSpecs: this.specs.size,
+			locales: [...this.locales],
+			domains: [...this.domains],
+			totalMessages
+		};
+	}
+	/**
+	* Clear all registered specs.
+	*/
+	clear() {
+		this.specs.clear();
+		this.latestByLocale.clear();
+		this.locales.clear();
+		this.domains.clear();
+	}
+	makeKey(key, version, locale) {
+		return `${key}:${version}:${locale}`;
+	}
+	isNewerVersion(a, b) {
+		const parseVersion = (v) => {
+			const parts = v.split(".").map(Number);
+			return {
+				major: parts[0] ?? 0,
+				minor: parts[1] ?? 0,
+				patch: parts[2] ?? 0
+			};
+		};
+		const va = parseVersion(a);
+		const vb = parseVersion(b);
+		if (va.major !== vb.major) return va.major > vb.major;
+		if (va.minor !== vb.minor) return va.minor > vb.minor;
+		return va.patch > vb.patch;
+	}
+};
+
+//#endregion
+export { TranslationRegistry };