@contractspec/lib.contracts 1.44.0

package/dist/telemetry/tracker.d.ts

@@ -0,0 +1,51 @@
+import { TelemetryEventDef, TelemetryRegistry, TelemetrySpec } from "./spec.js";
+import { TelemetryAnomalyMonitor } from "./anomaly.js";
+
+//#region src/telemetry/tracker.d.ts
+interface TelemetryEventContext {
+  tenantId?: string;
+  organizationId?: string | null;
+  userId?: string | null;
+  sessionId?: string | null;
+  actor?: 'anonymous' | 'user' | 'admin';
+  channel?: 'web' | 'mobile' | 'job' | 'agent';
+  metadata?: Record<string, unknown>;
+}
+interface TelemetryDispatch {
+  id: string;
+  name: string;
+  version: number;
+  occurredAt: string;
+  properties: Record<string, unknown>;
+  privacy: TelemetryEventDef['privacy'];
+  context: TelemetryEventContext;
+  tags?: string[];
+  spec: TelemetrySpec;
+  definition: TelemetryEventDef;
+}
+interface RuntimeTelemetryProvider {
+  id: string;
+  send(event: TelemetryDispatch): Promise<void>;
+}
+interface TelemetryTrackerOptions {
+  registry: TelemetryRegistry;
+  providers?: RuntimeTelemetryProvider[];
+  anomalyMonitor?: TelemetryAnomalyMonitor;
+  random?: () => number;
+  clock?: () => Date;
+}
+declare class TelemetryTracker {
+  private readonly providers;
+  private readonly registry;
+  private readonly anomalyMonitor?;
+  private readonly random;
+  private readonly clock;
+  constructor(options: TelemetryTrackerOptions);
+  registerProvider(provider: RuntimeTelemetryProvider): void;
+  unregisterProvider(providerId: string): void;
+  track(name: string, version: number, properties: Record<string, unknown>, context?: TelemetryEventContext): Promise<boolean>;
+  private shouldSample;
+  private redactProperties;
+}
+//#endregion
+export { RuntimeTelemetryProvider, TelemetryDispatch, TelemetryEventContext, TelemetryTracker, TelemetryTrackerOptions };

package/dist/telemetry/tracker.js

@@ -0,0 +1,76 @@
+import { randomUUID } from "crypto";
+
+//#region src/telemetry/tracker.ts
+const maskValue = (value) => {
+	if (value == null) return value;
+	if (typeof value === "string") return "REDACTED";
+	if (typeof value === "number") return 0;
+	if (typeof value === "boolean") return false;
+	if (Array.isArray(value)) return value.map(() => "REDACTED");
+	if (typeof value === "object") return Object.fromEntries(Object.keys(value).map((key) => [key, "REDACTED"]));
+	return "REDACTED";
+};
+var TelemetryTracker = class {
+	providers = /* @__PURE__ */ new Map();
+	registry;
+	anomalyMonitor;
+	random;
+	clock;
+	constructor(options) {
+		this.registry = options.registry;
+		this.anomalyMonitor = options.anomalyMonitor;
+		this.random = options.random ?? Math.random;
+		this.clock = options.clock ?? (() => /* @__PURE__ */ new Date());
+		for (const provider of options.providers ?? []) this.providers.set(provider.id, provider);
+	}
+	registerProvider(provider) {
+		this.providers.set(provider.id, provider);
+	}
+	unregisterProvider(providerId) {
+		this.providers.delete(providerId);
+	}
+	async track(name, version, properties, context = {}) {
+		const definition = this.registry.findEventDef(name, version);
+		if (!definition) return false;
+		const spec = this.registry.getSpecForEvent(definition.key, definition.version);
+		if (!spec) return false;
+		if (!this.shouldSample(definition.sampling ?? spec.config?.defaultSamplingRate)) return false;
+		const redactedProperties = this.redactProperties(definition, properties);
+		const dispatch = {
+			id: randomUUID(),
+			name: definition.key,
+			version: definition.version,
+			occurredAt: this.clock().toISOString(),
+			properties: redactedProperties,
+			privacy: definition.privacy,
+			context,
+			tags: definition.tags,
+			spec,
+			definition
+		};
+		await Promise.all([...this.providers.values()].map((provider) => provider.send(dispatch)));
+		this.anomalyMonitor?.observe(dispatch);
+		return true;
+	}
+	shouldSample(sampling) {
+		if (typeof sampling === "number") return this.random() < sampling;
+		if (!sampling) return true;
+		return this.random() < sampling.rate;
+	}
+	redactProperties(definition, properties) {
+		const result = {};
+		for (const [key, value] of Object.entries(properties)) {
+			const def = definition.properties[key];
+			if (!def) {
+				result[key] = value;
+				continue;
+			}
+			if (def.redact || def.pii || definition.privacy === "sensitive") result[key] = maskValue(value);
+			else result[key] = value;
+		}
+		return result;
+	}
+};
+
+//#endregion
+export { TelemetryTracker };

package/dist/tests/index.d.ts

@@ -0,0 +1,3 @@
+import { Action, Assertion, CoverageRequirement, ExpectErrorAssertion, ExpectEventsAssertion, ExpectOutputAssertion, ExpectedEvent, Fixture, OperationTargetRef, TestRegistry, TestScenario, TestSpec, TestSpecMeta, TestSpecRef, TestTarget, WorkflowTargetRef, makeTestKey } from "./spec.js";
+import { AssertionResult, ScenarioRunResult, TestRunResult, TestRunner, TestRunnerConfig } from "./runner.js";
+export { Action, Assertion, AssertionResult, CoverageRequirement, ExpectErrorAssertion, ExpectEventsAssertion, ExpectOutputAssertion, ExpectedEvent, Fixture, OperationTargetRef, ScenarioRunResult, TestRegistry, TestRunResult, TestRunner, TestRunnerConfig, TestScenario, TestSpec, TestSpecMeta, TestSpecRef, TestTarget, WorkflowTargetRef, makeTestKey };

package/dist/tests/index.js

@@ -0,0 +1,4 @@
+import { TestRegistry, makeTestKey } from "./spec.js";
+import { TestRunner } from "./runner.js";
+
+export { TestRegistry, TestRunner, makeTestKey };

package/dist/tests/runner.d.ts

@@ -0,0 +1,43 @@
+import { HandlerCtx } from "../types.js";
+import { Assertion, TestScenario, TestSpec } from "./spec.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
+import "../index.js";
+
+//#region src/tests/runner.d.ts
+interface ScenarioRunResult {
+  scenario: TestScenario;
+  status: 'passed' | 'failed';
+  error?: Error;
+  assertionResults: AssertionResult[];
+}
+interface AssertionResult {
+  assertion: Assertion;
+  status: 'passed' | 'failed';
+  message?: string;
+}
+interface TestRunResult {
+  spec: TestSpec;
+  scenarios: ScenarioRunResult[];
+  passed: number;
+  failed: number;
+}
+interface TestRunnerConfig {
+  registry: OperationSpecRegistry;
+  createContext?: () => HandlerCtx | Promise<HandlerCtx>;
+  beforeEach?: (scenario: TestScenario) => void | Promise<void>;
+  afterEach?: (scenario: TestScenario, result: ScenarioRunResult) => void | Promise<void>;
+}
+declare class TestRunner {
+  private readonly config;
+  constructor(config: TestRunnerConfig);
+  run(spec: TestSpec): Promise<TestRunResult>;
+  private runScenario;
+  private createContext;
+  private executeOperation;
+  private evaluateAssertion;
+  private evaluateOutputAssertion;
+  private evaluateErrorAssertion;
+  private evaluateEventsAssertion;
+}
+//#endregion
+export { AssertionResult, ScenarioRunResult, TestRunResult, TestRunner, TestRunnerConfig };

package/dist/tests/runner.js

@@ -0,0 +1,150 @@
+import "../index.js";
+import { deepStrictEqual } from "assert";
+
+//#region src/tests/runner.ts
+var TestRunner = class {
+	constructor(config) {
+		this.config = config;
+	}
+	async run(spec) {
+		const scenarios = [];
+		let passed = 0;
+		let failed = 0;
+		for (const scenario of spec.scenarios) {
+			await this.config.beforeEach?.(scenario);
+			const result = await this.runScenario(spec, scenario);
+			scenarios.push(result);
+			if (result.status === "passed") passed += 1;
+			else failed += 1;
+			await this.config.afterEach?.(scenario, result);
+		}
+		return {
+			spec,
+			scenarios,
+			passed,
+			failed
+		};
+	}
+	async runScenario(spec, scenario) {
+		const assertionResults = [];
+		try {
+			const context = await this.createContext();
+			const fixtures = [...spec.fixtures ?? [], ...scenario.given ?? []];
+			const events = [];
+			for (const fixture of fixtures) await this.executeOperation(fixture, context, events);
+			const actionResult = await this.executeOperation(scenario.when, context, events);
+			const assertions = scenario.then ?? [];
+			for (const assertion of assertions) {
+				const assertionResult = this.evaluateAssertion(assertion, actionResult, events);
+				assertionResults.push(assertionResult);
+			}
+			return {
+				scenario,
+				status: assertionResults.some((assertion) => assertion.status === "failed") ? "failed" : "passed",
+				assertionResults
+			};
+		} catch (error) {
+			return {
+				scenario,
+				status: "failed",
+				error,
+				assertionResults
+			};
+		}
+	}
+	async createContext() {
+		return { ...await this.config.createContext?.() ?? {} };
+	}
+	async executeOperation(action, baseCtx, recordedEvents) {
+		const ctx = {
+			...baseCtx,
+			eventPublisher: async (event) => {
+				recordedEvents.push({
+					key: event.key,
+					version: event.version,
+					payload: event.payload
+				});
+				await baseCtx.eventPublisher?.(event);
+			}
+		};
+		try {
+			return {
+				output: await this.config.registry.execute(action.operation.key, action.operation.version, action.input ?? null, ctx),
+				events: recordedEvents
+			};
+		} catch (error) {
+			return {
+				error,
+				events: recordedEvents
+			};
+		}
+	}
+	evaluateAssertion(assertion, result, events) {
+		switch (assertion.type) {
+			case "expectOutput": return this.evaluateOutputAssertion(assertion, result);
+			case "expectError": return this.evaluateErrorAssertion(assertion, result);
+			case "expectEvents": return this.evaluateEventsAssertion(assertion, events);
+			default: return {
+				assertion,
+				status: "failed",
+				message: `Unknown assertion type ${assertion.type}`
+			};
+		}
+	}
+	evaluateOutputAssertion(assertion, result) {
+		if (result.error) return {
+			assertion,
+			status: "failed",
+			message: `Expected output but operation threw error: ${result.error.message}`
+		};
+		try {
+			deepStrictEqual(result.output, assertion.match);
+			return {
+				assertion,
+				status: "passed"
+			};
+		} catch (error) {
+			return {
+				assertion,
+				status: "failed",
+				message: error instanceof Error ? error.message : "Output assertion failed"
+			};
+		}
+	}
+	evaluateErrorAssertion(assertion, result) {
+		if (!result.error) return {
+			assertion,
+			status: "failed",
+			message: "Expected an error but operation completed successfully"
+		};
+		if (assertion.messageIncludes && !result.error.message.includes(assertion.messageIncludes)) return {
+			assertion,
+			status: "failed",
+			message: `Error message "${result.error.message}" did not include expected substring "${assertion.messageIncludes}"`
+		};
+		return {
+			assertion,
+			status: "passed"
+		};
+	}
+	evaluateEventsAssertion(assertion, events) {
+		const failures = [];
+		for (const expected of assertion.events) {
+			const count = events.filter((event) => event.key === expected.key && event.version === expected.version).length;
+			if (typeof expected.min === "number" && count < expected.min || typeof expected.max === "number" && count > expected.max) failures.push(`Event ${expected.key}.v${expected.version} occurred ${count} times (expected ${expected.min ?? 0} - ${expected.max ?? "∞"})`);
+			else if (typeof expected.min === "undefined" && typeof expected.max === "undefined" && count === 0) failures.push(`Event ${expected.key}.v${expected.version} did not occur`);
+		}
+		if (failures.length > 0) return {
+			assertion,
+			status: "failed",
+			message: failures.join("; ")
+		};
+		return {
+			assertion,
+			status: "passed"
+		};
+	}
+};
+
+//#endregion
+export { TestRunner };

package/dist/tests/spec.d.ts

@@ -0,0 +1,81 @@
+import { OwnerShipMeta } from "../ownership.js";
+
+//#region src/tests/spec.d.ts
+interface OperationTargetRef {
+  key: string;
+  version?: number;
+}
+interface WorkflowTargetRef {
+  key: string;
+  version?: number;
+}
+type TestTarget = {
+  type: 'operation';
+  operation: OperationTargetRef;
+} | {
+  type: 'workflow';
+  workflow: WorkflowTargetRef;
+};
+interface Fixture {
+  description?: string;
+  operation: OperationTargetRef;
+  input?: unknown;
+}
+interface Action {
+  operation: OperationTargetRef;
+  input?: unknown;
+}
+interface ExpectOutputAssertion {
+  type: 'expectOutput';
+  match: unknown;
+}
+interface ExpectErrorAssertion {
+  type: 'expectError';
+  messageIncludes?: string;
+}
+interface ExpectedEvent {
+  key: string;
+  version: number;
+  min?: number;
+  max?: number;
+}
+interface ExpectEventsAssertion {
+  type: 'expectEvents';
+  events: ExpectedEvent[];
+}
+type Assertion = ExpectOutputAssertion | ExpectErrorAssertion | ExpectEventsAssertion;
+interface TestScenario {
+  key: string;
+  description?: string;
+  given?: Fixture[];
+  when: Action;
+  then?: Assertion[];
+}
+interface CoverageRequirement {
+  statements?: number;
+  branches?: number;
+  functions?: number;
+  lines?: number;
+  mutations?: number;
+}
+type TestSpecMeta = OwnerShipMeta;
+interface TestSpec {
+  meta: TestSpecMeta;
+  target: TestTarget;
+  fixtures?: Fixture[];
+  scenarios: TestScenario[];
+  coverage?: CoverageRequirement;
+}
+interface TestSpecRef {
+  key: string;
+  version?: number;
+}
+declare class TestRegistry {
+  private readonly items;
+  register(spec: TestSpec): this;
+  list(): TestSpec[];
+  get(name: string, version?: number): TestSpec | undefined;
+}
+declare function makeTestKey(meta: TestSpecMeta): string;
+//#endregion
+export { Action, Assertion, CoverageRequirement, ExpectErrorAssertion, ExpectEventsAssertion, ExpectOutputAssertion, ExpectedEvent, Fixture, OperationTargetRef, TestRegistry, TestScenario, TestSpec, TestSpecMeta, TestSpecRef, TestTarget, WorkflowTargetRef, makeTestKey };

package/dist/tests/spec.js

@@ -0,0 +1,33 @@
+//#region src/tests/spec.ts
+const testKey = (meta) => `${meta.key}.v${meta.version}`;
+var TestRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	register(spec) {
+		const key = testKey(spec.meta);
+		if (this.items.has(key)) throw new Error(`Duplicate TestSpec registration for ${key}`);
+		this.items.set(key, spec);
+		return this;
+	}
+	list() {
+		return [...this.items.values()];
+	}
+	get(name, version) {
+		if (version != null) return this.items.get(`${name}.v${version}`);
+		let latest;
+		let maxVersion = -Infinity;
+		for (const spec of this.items.values()) {
+			if (spec.meta.key !== name) continue;
+			if (spec.meta.version > maxVersion) {
+				maxVersion = spec.meta.version;
+				latest = spec;
+			}
+		}
+		return latest;
+	}
+};
+function makeTestKey(meta) {
+	return testKey(meta);
+}
+
+//#endregion
+export { TestRegistry, makeTestKey };

package/dist/themes.d.ts

@@ -0,0 +1,53 @@
+import { OwnerShipMeta } from "./ownership.js";
+
+//#region src/themes.d.ts
+type ThemeScope = 'global' | 'tenant' | 'user';
+interface ThemeToken<T> {
+  value: T;
+  description?: string;
+}
+interface ThemeTokens {
+  colors?: Record<string, ThemeToken<string>>;
+  radii?: Record<string, ThemeToken<number>>;
+  space?: Record<string, ThemeToken<number>>;
+  typography?: Record<string, ThemeToken<number>>;
+  shadows?: Record<string, ThemeToken<string>>;
+  motion?: Record<string, ThemeToken<string>>;
+}
+interface ComponentVariantDefinition {
+  props?: Record<string, unknown>;
+  tokens?: ThemeTokens;
+}
+interface ComponentVariantSpec {
+  component: string;
+  variants: Record<string, ComponentVariantDefinition>;
+}
+interface ThemeOverride {
+  scope: ThemeScope;
+  target: string;
+  tokens?: ThemeTokens;
+  components?: ComponentVariantSpec[];
+}
+interface ThemeMeta extends OwnerShipMeta {
+  extends?: ThemeRef;
+  scopes?: ThemeScope[];
+}
+interface ThemeSpec {
+  meta: ThemeMeta;
+  tokens: ThemeTokens;
+  components?: ComponentVariantSpec[];
+  overrides?: ThemeOverride[];
+}
+interface ThemeRef {
+  key: string;
+  version: number;
+}
+declare class ThemeRegistry {
+  private readonly items;
+  register(spec: ThemeSpec): this;
+  list(): ThemeSpec[];
+  get(key: string, version?: number): ThemeSpec | undefined;
+}
+declare function makeThemeRef(spec: ThemeSpec): ThemeRef;
+//#endregion
+export { ComponentVariantDefinition, ComponentVariantSpec, ThemeMeta, ThemeOverride, ThemeRef, ThemeRegistry, ThemeScope, ThemeSpec, ThemeToken, ThemeTokens, makeThemeRef };

package/dist/themes.js

@@ -0,0 +1,39 @@
+//#region src/themes.ts
+const themeKey = (ref) => `${ref.key}.v${ref.version}`;
+var ThemeRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	register(spec) {
+		const key = themeKey(spec.meta);
+		if (this.items.has(key)) throw new Error(`Duplicate theme ${key}`);
+		this.items.set(key, spec);
+		return this;
+	}
+	list() {
+		return [...this.items.values()];
+	}
+	get(key, version) {
+		if (version != null) return this.items.get(themeKey({
+			key,
+			version
+		}));
+		let candidate;
+		let max = -Infinity;
+		for (const spec of this.items.values()) {
+			if (spec.meta.key !== key) continue;
+			if (spec.meta.version > max) {
+				max = spec.meta.version;
+				candidate = spec;
+			}
+		}
+		return candidate;
+	}
+};
+function makeThemeRef(spec) {
+	return {
+		key: spec.meta.key,
+		version: spec.meta.version
+	};
+}
+
+//#endregion
+export { ThemeRegistry, makeThemeRef };

package/dist/translations/catalog.d.ts

@@ -0,0 +1,28 @@
+//#region src/translations/catalog.d.ts
+type Locale = string;
+type MessageKey = string;
+interface TranslationEntry {
+  key: MessageKey;
+  locale: Locale;
+  value: string;
+  context?: string;
+}
+interface TranslationCatalogMeta {
+  key: string;
+  version: number;
+  description?: string;
+}
+interface PlatformTranslationCatalog {
+  meta: TranslationCatalogMeta;
+  defaultLocale: Locale;
+  supportedLocales: Locale[];
+  entries: TranslationEntry[];
+}
+interface BlueprintTranslationCatalog {
+  meta: TranslationCatalogMeta;
+  defaultLocale: Locale;
+  supportedLocales: Locale[];
+  entries: TranslationEntry[];
+}
+//#endregion
+export { BlueprintTranslationCatalog, Locale, MessageKey, PlatformTranslationCatalog, TranslationCatalogMeta, TranslationEntry };

package/dist/translations/tenant.d.ts

@@ -0,0 +1,15 @@
+import { Locale, TranslationEntry } from "./catalog.js";
+
+//#region src/translations/tenant.d.ts
+interface TenantTranslationOverride {
+  tenantId: string;
+  appId: string;
+  blueprintName: string;
+  blueprintVersion: number;
+  entries: TranslationEntry[];
+  defaultLocale?: Locale;
+  enabledLocales?: Locale[];
+  updatedAt?: string;
+}
+//#endregion
+export { TenantTranslationOverride };

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+import { ConsentDefinition, PolicySpec, RateLimitDefinition } from "./policy/spec.js";
+import { TelemetryTracker } from "./telemetry/tracker.js";
+import "./telemetry/index.js";
+import { ResolvedBranding } from "./app-config/branding.js";
+import { Locale, MessageKey } from "./translations/catalog.js";
+import { ResolvedAppConfig, ResolvedIntegration, ResolvedKnowledge, ResolvedTranslation } from "./app-config/runtime.js";
+import { SecretProvider } from "./integrations/secrets/provider.js";
+import { SpecVariantResolver } from "./experiments/spec-resolver.js";
+import { EventRegistry } from "./events.js";
+
+//#region src/types.d.ts
+/**
+ * Common runtime types: execution context, policy decision & event emission.
+ */
+type Actor = 'anonymous' | 'user' | 'admin';
+type Channel = 'web' | 'mobile' | 'job' | 'agent';
+type ContractSpecType = 'app-config' | 'capability' | 'data-view' | 'experiment' | 'form' | 'integration' | 'knowledge' | 'operation' | 'policy' | 'presentation' | 'telemetry' | 'workflow' | 'event' | 'feature' | 'migration';
+interface FieldLevelDecision {
+  field: string;
+  effect: 'allow' | 'deny';
+  reason?: string;
+}
+interface PolicyDecision {
+  effect: 'allow' | 'deny';
+  reason?: string;
+  rateLimit?: Pick<RateLimitDefinition, 'rpm' | 'key' | 'windowSeconds' | 'burst'>;
+  escalate?: 'human_review' | null;
+  fieldDecisions?: FieldLevelDecision[];
+  pii?: PolicySpec['pii'];
+  requiredConsents?: ConsentDefinition[];
+  evaluatedBy?: 'engine' | 'opa';
+}
+interface PolicyDeciderInput {
+  service: string;
+  command: string;
+  version: number;
+  actor: Actor;
+  channel?: Channel;
+  roles?: string[];
+  organizationId?: string | null;
+  userId?: string | null;
+  flags?: string[];
+}
+type PolicyDecider = (input: PolicyDeciderInput) => Promise<PolicyDecision>;
+type RateLimiter = (key: string, cost: number, rpm: number) => Promise<void>;
+type TranslationResolver = (key: MessageKey, locale?: Locale) => Promise<string | null> | string | null;
+/** Outbox/bus event publisher (after validation & guarding) */
+type EventPublisher = (envelope: {
+  key: string;
+  version: number;
+  payload: unknown;
+  traceId?: string;
+}) => Promise<void>;
+interface HandlerCtx {
+  traceId?: string;
+  idemKey?: string;
+  organizationId?: string | null;
+  userId?: string | null;
+  actor?: Actor;
+  channel?: Channel;
+  roles?: string[];
+  /** Policy engine hook (policy.yaml) */
+  decide?: PolicyDecider;
+  /** Rate limiter (e.g., Redis) */
+  rateLimit?: RateLimiter;
+  /** Telemetry tracker */
+  telemetry?: TelemetryTracker;
+  /** Event publisher (outbox+bus) */
+  eventPublisher?: EventPublisher;
+  /** Secret provider for secure credentials */
+  secretProvider?: SecretProvider;
+  /** Internal pipe: filled by executor to enforce declared events */
+  __emitGuard__?: (key: string, version: number, payload: unknown) => Promise<void>;
+  /** Resolved application configuration for the current execution context */
+  appConfig?: ResolvedAppConfig;
+  /** Resolved integration connections available to this execution */
+  integrations?: ResolvedIntegration[];
+  /** Resolved knowledge spaces available to this execution */
+  knowledge?: ResolvedKnowledge[];
+  /** Resolved branding context */
+  branding?: ResolvedBranding;
+  /** Translation context */
+  translation?: {
+    config: ResolvedTranslation;
+    resolve?: TranslationResolver;
+  };
+  /** Optional spec variant resolver for experiments */
+  specVariantResolver?: SpecVariantResolver;
+  eventSpecResolver?: EventRegistry;
+}
+//#endregion
+export { Actor, Channel, ContractSpecType, EventPublisher, FieldLevelDecision, HandlerCtx, PolicyDecider, PolicyDeciderInput, PolicyDecision, RateLimiter, TranslationResolver };