@contractspec/lib.contracts 1.49.0 → 1.51.0

package/dist/capabilities/validation.js

@@ -0,0 +1,141 @@
+//#region src/capabilities/validation.ts
+/**
+* Validates bidirectional consistency between capabilities and their surfaces.
+*
+* Checks:
+* 1. Forward validation: Every surface ref in capability `provides` exists
+* 2. Reverse validation: Every spec with `capability` field is in that capability's `provides`
+*
+* @param deps - Registries to validate against
+* @returns Validation result with errors and warnings
+*
+* @example
+* ```typescript
+* const result = validateCapabilityConsistency({
+*   capabilities: capabilityRegistry,
+*   operations: operationRegistry,
+*   events: eventRegistry,
+* });
+*
+* if (!result.valid) {
+*   console.error('Capability validation failed:', result.errors);
+* }
+* ```
+*/
+function validateCapabilityConsistency(deps) {
+	const errors = [];
+	const warnings = [];
+	for (const capability of deps.capabilities.list()) {
+		const capKey = `${capability.meta.key}.v${capability.meta.version}`;
+		for (const surface of capability.provides ?? []) if (!checkSurfaceExists(deps, surface.surface, surface.key)) errors.push({
+			type: "missing_surface_spec",
+			message: `Capability "${capKey}" provides ${surface.surface} "${surface.key}" but spec not found`,
+			capabilityKey: capKey,
+			surface: surface.surface,
+			specKey: surface.key
+		});
+	}
+	if (deps.operations) {
+		for (const op of deps.operations.list()) if (op.capability) {
+			const capSpec = deps.capabilities.get(op.capability.key, op.capability.version);
+			if (!capSpec) errors.push({
+				type: "capability_not_found",
+				message: `Operation "${op.meta.key}" references capability "${op.capability.key}.v${op.capability.version}" but capability not found`,
+				specKey: op.meta.key,
+				capabilityKey: `${op.capability.key}.v${op.capability.version}`,
+				surface: "operation"
+			});
+			else if (!capSpec.provides?.some((p) => p.surface === "operation" && p.key === op.meta.key)) errors.push({
+				type: "surface_not_in_provides",
+				message: `Operation "${op.meta.key}" claims capability "${op.capability.key}.v${op.capability.version}" but not in capability's provides`,
+				specKey: op.meta.key,
+				capabilityKey: `${op.capability.key}.v${op.capability.version}`,
+				surface: "operation"
+			});
+		}
+	}
+	if (deps.events) {
+		for (const event of deps.events.list()) if (event.capability) {
+			const capSpec = deps.capabilities.get(event.capability.key, event.capability.version);
+			if (!capSpec) errors.push({
+				type: "capability_not_found",
+				message: `Event "${event.meta.key}" references capability "${event.capability.key}.v${event.capability.version}" but capability not found`,
+				specKey: event.meta.key,
+				capabilityKey: `${event.capability.key}.v${event.capability.version}`,
+				surface: "event"
+			});
+			else if (!capSpec.provides?.some((p) => p.surface === "event" && p.key === event.meta.key)) errors.push({
+				type: "surface_not_in_provides",
+				message: `Event "${event.meta.key}" claims capability "${event.capability.key}.v${event.capability.version}" but not in capability's provides`,
+				specKey: event.meta.key,
+				capabilityKey: `${event.capability.key}.v${event.capability.version}`,
+				surface: "event"
+			});
+		}
+	}
+	if (deps.presentations) {
+		for (const pres of deps.presentations.list()) if (pres.capability) {
+			const capSpec = deps.capabilities.get(pres.capability.key, pres.capability.version);
+			if (!capSpec) errors.push({
+				type: "capability_not_found",
+				message: `Presentation "${pres.meta.key}" references capability "${pres.capability.key}.v${pres.capability.version}" but capability not found`,
+				specKey: pres.meta.key,
+				capabilityKey: `${pres.capability.key}.v${pres.capability.version}`,
+				surface: "presentation"
+			});
+			else if (!capSpec.provides?.some((p) => p.surface === "presentation" && p.key === pres.meta.key)) errors.push({
+				type: "surface_not_in_provides",
+				message: `Presentation "${pres.meta.key}" claims capability "${pres.capability.key}.v${pres.capability.version}" but not in capability's provides`,
+				specKey: pres.meta.key,
+				capabilityKey: `${pres.capability.key}.v${pres.capability.version}`,
+				surface: "presentation"
+			});
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+/**
+* Check if a spec exists for a given surface type and key.
+*/
+function checkSurfaceExists(deps, surface, key) {
+	switch (surface) {
+		case "operation": return deps.operations?.has(key) ?? true;
+		case "event": return deps.events?.has(key) ?? true;
+		case "presentation": return deps.presentations?.has(key) ?? true;
+		case "workflow":
+		case "resource": return true;
+		default: return true;
+	}
+}
+/**
+* Finds specs that have no capability assignment (orphan specs).
+* This is informational - orphan specs are allowed but may indicate
+* incomplete capability modeling.
+*
+* @param deps - Registries to check
+* @returns List of spec keys without capability assignment
+*/
+function findOrphanSpecs(deps) {
+	const result = {
+		operations: [],
+		events: [],
+		presentations: []
+	};
+	if (deps.operations) {
+		for (const op of deps.operations.list()) if (!op.capability) result.operations.push(op.meta.key);
+	}
+	if (deps.events) {
+		for (const event of deps.events.list()) if (!event.capability) result.events.push(event.meta.key);
+	}
+	if (deps.presentations) {
+		for (const pres of deps.presentations.list()) if (!pres.capability) result.presentations.push(pres.meta.key);
+	}
+	return result;
+}
+
+//#endregion
+export { findOrphanSpecs, validateCapabilityConsistency };

package/dist/client/react/feature-render.d.ts

@@ -1,8 +1,8 @@
 import { PresentationSpec, PresentationTarget } from "../../presentations/presentations.js";
-import { FeatureModuleSpec } from "../../features/types.js";
-import { FeatureRegistry } from "../../features/registry.js";
 import { ComponentMap, TransformEngine } from "../../presentations/transform-engine.js";
 import "../../presentations/index.js";
+import { FeatureModuleSpec } from "../../features/types.js";
+import { FeatureRegistry } from "../../features/registry.js";
 import "../../features/index.js";
 import React from "react";
 import { BlockConfig } from "@blocknote/core";

package/dist/data-views/runtime.d.ts

@@ -1,5 +1,5 @@
-import { OperationSpecRegistry } from "../operations/registry.js";
 import "../operations/index.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
 import { DataViewSpec } from "./spec.js";
 import { DataViewRegistry } from "./registry.js";
 import "./index.js";

package/dist/events.d.ts

@@ -1,45 +1,111 @@
+import { CapabilityRef } from "./capabilities/capabilities.js";
 import { DocId } from "./docs/registry.js";
 import { OwnerShipMeta } from "./ownership.js";
 import { SpecContractRegistry } from "./registry.js";
 import { AnySchemaModel } from "@contractspec/lib.schema";
 
 //#region src/events.d.ts
+
+/**
+ * Metadata for an event specification.
+ * Extends OwnerShipMeta with event-specific documentation.
+ */
 interface EventSpecMeta extends Omit<OwnerShipMeta, 'docId'> {
-  /** Doc block(s) for this operation. */
+  /** Associated DocBlock identifiers for this event. */
   docId?: DocId[];
 }
 /**
- * Typed event specification. Declare once, validate payloads at publish time,
- * and guard emissions via the contracts runtime.
+ * Typed event specification.
+ *
+ * Declare once, validate payloads at publish time, and guard emissions
+ * via the contracts runtime. Events are the backbone of event-driven
+ * architectures in ContractSpec.
+ *
+ * @typeParam T - The SchemaModel type defining the event payload structure
  */
 interface EventSpec<T extends AnySchemaModel> {
+  /** Event metadata including key, version, and ownership. */
   meta: EventSpecMeta;
-  /** JSON-like paths to redact from logs/exports. */
+  /**
+   * Optional reference to the capability that provides this event.
+   * Used for bidirectional linking between capabilities and events.
+   */
+  capability?: CapabilityRef;
+  /**
+   * JSON paths to PII fields that should be redacted in logs/exports.
+   * @example ['email', 'user.phone', 'billing.address']
+   */
   pii?: string[];
   /** Event payload schema from @contractspec/lib.schema. */
   payload: T;
 }
+/**
+ * Type alias for any EventSpec regardless of payload type.
+ * Useful for collections and registries.
+ */
 type AnyEventSpec<T extends AnySchemaModel = AnySchemaModel> = EventSpec<T>;
-/** Identity function to keep type inference when declaring events. */
+/**
+ * Identity function to define an event spec with full type inference.
+ *
+ * @param e - The event specification
+ * @returns The same event specification with preserved types
+ *
+ * @example
+ * ```typescript
+ * const MyEvent = defineEvent({
+ *   meta: { key: 'my.event', version: '1.0.0', ... },
+ *   payload: myPayloadSchema,
+ * });
+ * ```
+ */
 declare function defineEvent<T extends AnySchemaModel>(e: EventSpec<T>): EventSpec<T>;
+/**
+ * Wrapper for a published event with metadata.
+ *
+ * Used when events are serialized for transport or storage.
+ * Contains the validated payload plus envelope metadata.
+ *
+ * @typeParam T - The payload type
+ */
 interface EventEnvelope<T> {
-  /** Unique identifier for the published event (UUID recommended). */
+  /** Unique identifier for this event instance (UUID recommended). */
   id: string;
-  /** ISO timestamp when the event occurred. */
+  /** ISO 8601 timestamp when the event occurred. */
   occurredAt: string;
-  /** Optional trace identifier for correlating across services. */
+  /** Trace identifier for correlating across services. */
   traceId?: string;
-  /** Event name as published (should match spec.name). */
+  /** Event key (should match spec.meta.key). */
   key: string;
-  /** Event version as published (should match spec.version). */
+  /** Event version (should match spec.meta.version). */
   version: string;
-  /** Validated payload. */
+  /** Validated event payload. */
   payload: T;
 }
+/**
+ * Template literal type for event keys.
+ * Format: "key.vversion" (e.g., "user.created.v1.0.0")
+ */
 type EventKey = `${string}.v${string}`;
-/** Build a stable string key for an event name/version pair. */
+/**
+ * Builds a stable string key for an event name/version pair.
+ *
+ * @param key - The event key (e.g., "user.created")
+ * @param version - The event version (e.g., "1.0.0")
+ * @returns A string in format "key.vversion"
+ *
+ * @example
+ * ```typescript
+ * const key = eventKey('user.created', '1.0.0');
+ * // "user.created.v1.0.0"
+ * ```
+ */
 declare const eventKey: (key: string, version: string) => EventKey;
-/** In-memory registry for EventSpec. */
+/**
+ * In-memory registry for EventSpec instances.
+ *
+ * Provides registration, lookup, and listing of event specifications.
+ * Used by the contracts runtime to validate event emissions.
+ */
 declare class EventRegistry extends SpecContractRegistry<'event', AnyEventSpec> {
   constructor(items?: AnyEventSpec[]);
 }

package/dist/events.js

@@ -2,13 +2,43 @@ import { SpecContractRegistry } from "./registry.js";
 import "@contractspec/lib.schema";
 
 //#region src/events.ts
-/** Identity function to keep type inference when declaring events. */
+/**
+* Identity function to define an event spec with full type inference.
+*
+* @param e - The event specification
+* @returns The same event specification with preserved types
+*
+* @example
+* ```typescript
+* const MyEvent = defineEvent({
+*   meta: { key: 'my.event', version: '1.0.0', ... },
+*   payload: myPayloadSchema,
+* });
+* ```
+*/
 function defineEvent(e) {
 	return e;
 }
-/** Build a stable string key for an event name/version pair. */
+/**
+* Builds a stable string key for an event name/version pair.
+*
+* @param key - The event key (e.g., "user.created")
+* @param version - The event version (e.g., "1.0.0")
+* @returns A string in format "key.vversion"
+*
+* @example
+* ```typescript
+* const key = eventKey('user.created', '1.0.0');
+* // "user.created.v1.0.0"
+* ```
+*/
 const eventKey = (key, version) => `${key}.v${version}`;
-/** In-memory registry for EventSpec. */
+/**
+* In-memory registry for EventSpec instances.
+*
+* Provides registration, lookup, and listing of event specifications.
+* Used by the contracts runtime to validate event emissions.
+*/
 var EventRegistry = class extends SpecContractRegistry {
 	constructor(items) {
 		super("event", items);

package/dist/examples/schema.d.ts

@@ -3,14 +3,14 @@ import { z as z$1 } from "zod";
 
 //#region src/examples/schema.d.ts
 declare const ExampleKindSchema: z$1.ZodEnum<{
-  library: "library";
-  workflow: "workflow";
-  integration: "integration";
   knowledge: "knowledge";
   template: "template";
+  workflow: "workflow";
+  integration: "integration";
   blueprint: "blueprint";
   ui: "ui";
   script: "script";
+  library: "library";
 }>;
 declare const ExampleVisibilitySchema: z$1.ZodEnum<{
   experimental: "experimental";
@@ -104,14 +104,14 @@ declare const ExampleMetaSchema: z$1.ZodObject<{
   tags: z$1.ZodArray<z$1.ZodString>;
   docId: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
   kind: z$1.ZodEnum<{
-    library: "library";
-    workflow: "workflow";
-    integration: "integration";
     knowledge: "knowledge";
     template: "template";
+    workflow: "workflow";
+    integration: "integration";
     blueprint: "blueprint";
     ui: "ui";
     script: "script";
+    library: "library";
   }>;
   visibility: z$1.ZodEnum<{
     experimental: "experimental";
@@ -152,14 +152,14 @@ declare const ExampleSpecSchema: z$1.ZodObject<{
     tags: z$1.ZodArray<z$1.ZodString>;
     docId: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
     kind: z$1.ZodEnum<{
-      library: "library";
-      workflow: "workflow";
-      integration: "integration";
       knowledge: "knowledge";
       template: "template";
+      workflow: "workflow";
+      integration: "integration";
       blueprint: "blueprint";
       ui: "ui";
       script: "script";
+      library: "library";
     }>;
     visibility: z$1.ZodEnum<{
       experimental: "experimental";
@@ -224,7 +224,7 @@ declare function safeParseExampleSpec(data: unknown): z$1.ZodSafeParseResult<{
     stability: "idea" | "in_creation" | "experimental" | "beta" | "stable" | "deprecated";
     owners: string[];
     tags: string[];
-    kind: "library" | "workflow" | "integration" | "knowledge" | "template" | "blueprint" | "ui" | "script";
+    kind: "knowledge" | "template" | "workflow" | "integration" | "blueprint" | "ui" | "script" | "library";
     visibility: "experimental" | "public" | "internal";
     title?: string | undefined;
     domain?: string | undefined;

package/dist/experiments/spec.d.ts

@@ -1,14 +1,17 @@
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 import { OwnerShipMeta } from "../ownership.js";
 import { PolicyRef } from "../policy/spec.js";
 import { TelemetryEventDef } from "../telemetry/spec.js";
 import { SpecContractRegistry } from "../registry.js";
 
 //#region src/experiments/spec.d.ts
+/** Metadata for an experiment spec. */
 type ExperimentMeta = OwnerShipMeta;
-interface ExperimentRef {
-  key: string;
-  version?: string;
-}
+/**
+ * Reference to an experiment spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type ExperimentRef = OptionalVersionedSpecRef;
 type ExperimentOverrideType = 'dataView' | 'workflow' | 'theme' | 'policy' | 'presentation';
 interface ExperimentOverride {
   type: ExperimentOverrideType;

package/dist/features/install.d.ts

@@ -1,11 +1,11 @@
-import { PresentationSpec } from "../presentations/presentations.js";
 import { CapabilityRegistry } from "../capabilities/capabilities.js";
-import "../capabilities/index.js";
+import { PresentationSpec } from "../presentations/presentations.js";
 import { OperationSpecRegistry } from "../operations/registry.js";
-import { FeatureModuleSpec } from "./types.js";
-import { FeatureRegistry } from "./registry.js";
 import { PresentationRegistry } from "../presentations/registry.js";
 import "../presentations/index.js";
+import "../capabilities/index.js";
+import { FeatureModuleSpec } from "./types.js";
+import { FeatureRegistry } from "./registry.js";
 
 //#region src/features/install.d.ts
 /** Dependencies for installing a feature. */

package/dist/features/types.d.ts

@@ -1,46 +1,40 @@
+import { SpecKeyRef, VersionedSpecRef } from "../versioning/refs.js";
+import { CapabilityRef, CapabilityRequirement } from "../capabilities/capabilities.js";
 import { PresentationTarget } from "../presentations/presentations.js";
 import { OwnerShipMeta } from "../ownership.js";
-import { CapabilityRef, CapabilityRequirement } from "../capabilities/capabilities.js";
-import "../capabilities/index.js";
-import { ExperimentRef } from "../experiments/spec.js";
 import { ImplementationRef } from "../operations/operation.js";
 import "../operations/index.js";
+import "../capabilities/index.js";
+import { ExperimentRef } from "../experiments/spec.js";
 
 //#region src/features/types.d.ts
 /** Minimal metadata to identify and categorize a feature module. */
 type FeatureModuleMeta = OwnerShipMeta;
-interface OpRef {
-  /** Operation key (OperationSpec.meta.key). */
-  key: string;
-  /** Operation version (OperationSpec.meta.version). */
-  version: string;
-}
-interface EventRef {
-  /** Event key. */
-  key: string;
-  /** Event version. */
-  version: string;
-}
-interface PresentationRef {
-  /** Presentation key. */
-  key: string;
-  /** Presentation version. */
-  version: string;
-}
+/**
+ * Reference to an operation spec.
+ * Uses key (OperationSpec.meta.key) and version (OperationSpec.meta.version).
+ */
+type OpRef = VersionedSpecRef;
+/**
+ * Reference to an event spec.
+ * Uses key (EventSpec.meta.key) and version (EventSpec.meta.version).
+ */
+type EventRef = VersionedSpecRef;
+/**
+ * Reference to a presentation spec.
+ * Uses key (PresentationSpec.meta.key) and version (PresentationSpec.meta.version).
+ */
+type PresentationRef = VersionedSpecRef;
 /**
  * Reference to a data view spec.
+ * Uses key (DataViewSpec.meta.key) and version (DataViewSpec.meta.version).
  */
-interface DataViewRef {
-  key: string;
-  version: string;
-}
+type DataViewRef = VersionedSpecRef;
 /**
  * Reference to a form spec.
+ * Uses key (FormSpec.meta.key) and version (FormSpec.meta.version).
  */
-interface FormRef {
-  key: string;
-  version: string;
-}
+type FormRef = VersionedSpecRef;
 /** Group operations/events/presentations into an installable feature. */
 interface FeatureModuleSpec {
   meta: FeatureModuleMeta;
@@ -81,8 +75,10 @@ interface FeatureModuleSpec {
   /** Forms associated with this feature. */
   forms?: FormRef[];
 }
-interface FeatureRef {
-  key: string;
-}
+/**
+ * Reference to a feature (unversioned).
+ * Features are identified by key only, without version pinning.
+ */
+type FeatureRef = SpecKeyRef;
 //#endregion
 export { DataViewRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, FormRef, OpRef, PresentationRef };