@contractspec/lib.contracts 0.0.0-canary-20260119224949 → 0.0.0-canary-20260128200020

package/dist/events.d.ts

@@ -1,45 +1,111 @@
+import { CapabilityRef } from "./capabilities/capabilities.js";
+import { SpecContractRegistry } from "./registry.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

@@ -18,19 +18,19 @@ declare const ExampleVisibilitySchema: z$1.ZodEnum<{
   internal: "internal";
 }>;
 declare const ExampleSandboxModeSchema: z$1.ZodEnum<{
+  markdown: "markdown";
   playground: "playground";
   specs: "specs";
   builder: "builder";
-  markdown: "markdown";
   evolution: "evolution";
 }>;
 declare const StabilitySchema: z$1.ZodEnum<{
-  deprecated: "deprecated";
   idea: "idea";
   in_creation: "in_creation";
   experimental: "experimental";
   beta: "beta";
   stable: "stable";
+  deprecated: "deprecated";
 }>;
 declare const ExampleDocumentationSchema: z$1.ZodObject<{
   rootDocId: z$1.ZodOptional<z$1.ZodString>;
@@ -42,10 +42,10 @@ declare const ExampleDocumentationSchema: z$1.ZodObject<{
 declare const ExampleSandboxSupportSchema: z$1.ZodObject<{
   enabled: z$1.ZodBoolean;
   modes: z$1.ZodArray<z$1.ZodEnum<{
+    markdown: "markdown";
     playground: "playground";
     specs: "specs";
     builder: "builder";
-    markdown: "markdown";
     evolution: "evolution";
   }>>;
 }, z$1.core.$strip>;
@@ -61,10 +61,10 @@ declare const ExampleSurfacesSchema: z$1.ZodObject<{
   sandbox: z$1.ZodObject<{
     enabled: z$1.ZodBoolean;
     modes: z$1.ZodArray<z$1.ZodEnum<{
+      markdown: "markdown";
       playground: "playground";
       specs: "specs";
       builder: "builder";
-      markdown: "markdown";
       evolution: "evolution";
     }>>;
   }, z$1.core.$strip>;
@@ -93,12 +93,12 @@ declare const ExampleMetaSchema: z$1.ZodObject<{
   description: z$1.ZodString;
   domain: z$1.ZodOptional<z$1.ZodString>;
   stability: z$1.ZodEnum<{
-    deprecated: "deprecated";
     idea: "idea";
     in_creation: "in_creation";
     experimental: "experimental";
     beta: "beta";
     stable: "stable";
+    deprecated: "deprecated";
   }>;
   owners: z$1.ZodArray<z$1.ZodString>;
   tags: z$1.ZodArray<z$1.ZodString>;
@@ -141,12 +141,12 @@ declare const ExampleSpecSchema: z$1.ZodObject<{
     description: z$1.ZodString;
     domain: z$1.ZodOptional<z$1.ZodString>;
     stability: z$1.ZodEnum<{
-      deprecated: "deprecated";
       idea: "idea";
       in_creation: "in_creation";
       experimental: "experimental";
       beta: "beta";
       stable: "stable";
+      deprecated: "deprecated";
     }>;
     owners: z$1.ZodArray<z$1.ZodString>;
     tags: z$1.ZodArray<z$1.ZodString>;
@@ -180,10 +180,10 @@ declare const ExampleSpecSchema: z$1.ZodObject<{
     sandbox: z$1.ZodObject<{
       enabled: z$1.ZodBoolean;
       modes: z$1.ZodArray<z$1.ZodEnum<{
+        markdown: "markdown";
         playground: "playground";
         specs: "specs";
         builder: "builder";
-        markdown: "markdown";
         evolution: "evolution";
       }>>;
     }, z$1.core.$strip>;
@@ -221,7 +221,7 @@ declare function safeParseExampleSpec(data: unknown): z$1.ZodSafeParseResult<{
     version: string;
     key: string;
     description: string;
-    stability: "deprecated" | "idea" | "in_creation" | "experimental" | "beta" | "stable";
+    stability: "idea" | "in_creation" | "experimental" | "beta" | "stable" | "deprecated";
     owners: string[];
     tags: string[];
     kind: "template" | "workflow" | "integration" | "knowledge" | "blueprint" | "ui" | "script" | "library";
@@ -235,7 +235,7 @@ declare function safeParseExampleSpec(data: unknown): z$1.ZodSafeParseResult<{
     templates: boolean;
     sandbox: {
       enabled: boolean;
-      modes: ("playground" | "specs" | "builder" | "markdown" | "evolution")[];
+      modes: ("markdown" | "playground" | "specs" | "builder" | "evolution")[];
     };
     studio: {
       enabled: boolean;

package/dist/examples/types.d.ts

@@ -1,7 +1,7 @@
-import { OwnerShipMeta } from "../ownership.js";
 import { FeatureModuleSpec, FeatureRef } from "../features/types.js";
 import "../features/index.js";
 import { AppBlueprintSpec, SpecPointer } from "../app-config/spec.js";
+import { OwnerShipMeta } from "../ownership.js";
 
 //#region src/examples/types.d.ts
 /** Kind of example - determines how it's presented in catalogs */

package/dist/experiments/spec.d.ts

@@ -1,14 +1,17 @@
-import { OwnerShipMeta } from "../ownership.js";
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 import { PolicyRef } from "../policy/spec.js";
-import { TelemetryEventDef } from "../telemetry/spec.js";
 import { SpecContractRegistry } from "../registry.js";
+import { TelemetryEventDef } from "../telemetry/spec.js";
+import { OwnerShipMeta } from "../ownership.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/index.d.ts

@@ -1,4 +1,4 @@
-import { EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, OpRef, PresentationRef } from "./types.js";
+import { DataViewRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, FormRef, OpRef, PresentationRef } from "./types.js";
 import { FeatureRegistry } from "./registry.js";
 import { InstallFeatureDeps, installFeature } from "./install.js";
 import { validateFeatureTargetsV2 } from "./validation.js";
@@ -10,4 +10,4 @@ import { validateFeatureTargetsV2 } from "./validation.js";
  */
 declare const defineFeature: (spec: FeatureModuleSpec) => FeatureModuleSpec;
 //#endregion
-export { type EventRef, type FeatureModuleMeta, type FeatureModuleSpec, type FeatureRef, FeatureRegistry, type InstallFeatureDeps, type OpRef, type PresentationRef, defineFeature, installFeature, validateFeatureTargetsV2 };
+export { type DataViewRef, type EventRef, type FeatureModuleMeta, type FeatureModuleSpec, type FeatureRef, FeatureRegistry, type FormRef, type InstallFeatureDeps, type OpRef, type PresentationRef, defineFeature, installFeature, validateFeatureTargetsV2 };

package/dist/features/install.d.ts

@@ -1,11 +1,11 @@
-import { PresentationSpec } from "../presentations/presentations.js";
 import { CapabilityRegistry } from "../capabilities/capabilities.js";
+import { PresentationSpec } from "../presentations/presentations.js";
+import { PresentationRegistry } from "../presentations/registry.js";
+import "../presentations/index.js";
 import "../capabilities/index.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 { OperationSpecRegistry } from "../operations/registry.js";
 
 //#region src/features/install.d.ts
 /** Dependencies for installing a feature. */

package/dist/features/types.d.ts

@@ -1,46 +1,40 @@
-import { PresentationTarget } from "../presentations/presentations.js";
-import { OwnerShipMeta } from "../ownership.js";
+import { SpecKeyRef, VersionedSpecRef } from "../versioning/refs.js";
 import { CapabilityRef, CapabilityRequirement } from "../capabilities/capabilities.js";
+import { ImplementationRef } from "../operations/operation.js";
+import { PresentationTarget } from "../presentations/presentations.js";
 import "../capabilities/index.js";
 import { ExperimentRef } from "../experiments/spec.js";
-import { ImplementationRef } from "../operations/operation.js";
 import "../operations/index.js";
+import { OwnerShipMeta } from "../ownership.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 };

package/dist/forms/forms.d.ts

@@ -1,5 +1,5 @@
-import { OwnerShipMeta } from "../ownership.js";
 import { GroupKeyFn, RegistryFilter } from "../registry-utils.js";
+import { OwnerShipMeta } from "../ownership.js";
 import { AnySchemaModel, ZodSchemaModel } from "@contractspec/lib.schema";
 
 //#region src/forms/forms.d.ts