@contractspec/lib.feature-flags 1.49.0 → 1.51.0

package/dist/contracts/src/capabilities/capabilities.d.ts

@@ -1,31 +1,58 @@
+import { VersionedSpecRef } from "../versioning/refs.js";
 import { OwnerShipMeta } from "../ownership.js";
 
 //#region ../contracts/src/capabilities/capabilities.d.ts
+/** Classification of capability types. */
 type CapabilityKind = 'api' | 'event' | 'data' | 'ui' | 'integration';
+/** Surfaces where capabilities can be exposed or consumed. */
 type CapabilitySurface = 'operation' | 'event' | 'workflow' | 'presentation' | 'resource';
+/**
+ * Reference to a capability on a specific surface.
+ * Extends VersionedSpecRef with surface and description context.
+ */
 interface CapabilitySurfaceRef {
+  /** The surface type where this capability is exposed. */
   surface: CapabilitySurface;
+  /** Unique key identifying the spec on that surface (e.g., operation key). */
   key: string;
-  version: string;
+  /** Semantic version of the spec on that surface. */
+  version?: string;
+  /** Optional description of what this capability provides. */
   description?: string;
 }
+/** Metadata for a capability spec, extending ownership with kind. */
 interface CapabilityMeta extends OwnerShipMeta {
+  /** The kind/category of this capability. */
   kind: CapabilityKind;
 }
+/**
+ * Requirement for a capability dependency.
+ * Used to declare what capabilities a spec needs.
+ */
 interface CapabilityRequirement {
+  /** Unique key of the required capability. */
   key: string;
+  /** Optional specific version required. */
   version?: string;
+  /** Optional kind filter for the requirement. */
   kind?: CapabilityKind;
+  /** If true, the requirement is optional and won't block if missing. */
   optional?: boolean;
+  /** Human-readable reason why this capability is required. */
   reason?: string;
 }
-interface CapabilityRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a capability spec.
+ * Uses key and version to identify a specific capability.
+ */
+type CapabilityRef = VersionedSpecRef;
 interface CapabilitySpec {
   meta: CapabilityMeta;
+  /** Capabilities this capability extends (inherits requirements from). */
+  extends?: CapabilityRef;
+  /** Surfaces (operations, events, presentations, etc.) this capability provides. */
   provides?: CapabilitySurfaceRef[];
+  /** Capabilities that must be present for this capability to function. */
   requires?: CapabilityRequirement[];
 }
 //#endregion

package/dist/contracts/src/capabilities/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","names":[],"sources":["../../../../../contracts/src/capabilities/capabilities.ts"],"sourcesContent":[],"mappings":";;;KAGY,cAAA;KAEA,iBAAA;AAFA,UASK,oBAAA,CATS;EAEd,OAAA,EAQD,iBARkB;EAOZ,GAAA,EAAA,MAAA;EAOA,OAAA,EAAA,MAAA;EAIA,WAAA,CAAA,EAAA,MAAA;AAQjB;AAKiB,UAjBA,cAAA,SAAuB,aAiBT,CAAA;EACvB,IAAA,EAjBA,cAiBA;;AAEK,UAhBI,qBAAA,CAgBJ;EAAqB,GAAA,EAAA,MAAA;;SAbzB;;;;UAKQ,aAAA;;;;UAKA,cAAA;QACT;aACK;aACA"}
+{"version":3,"file":"capabilities.d.ts","names":[],"sources":["../../../../../contracts/src/capabilities/capabilities.ts"],"sourcesContent":[],"mappings":";;;;;KAKY,cAAA;AAAZ;AAGY,KAAA,iBAAA,GAAiB,WAAA,GAAA,OAAA,GAAA,UAAA,GAAA,cAAA,GAAA,UAAA;AAW7B;AAYA;AASA;AAiBA;AAEiB,UAxCA,oBAAA,CAwCc;EACvB;EAEI,OAAA,EAzCD,iBAyCC;EAEC;EAEA,GAAA,EAAA,MAAA;EAAqB;;;;;;UAnCjB,cAAA,SAAuB;;QAEhC;;;;;;UAOS,qBAAA;;;;;;SAMR;;;;;;;;;;KAWG,aAAA,GAAgB;UAEX,cAAA;QACT;;YAEI;;aAEC;;aAEA"}

package/dist/contracts/src/capabilities/context.d.ts

@@ -0,0 +1 @@
+import "./capabilities.js";

package/dist/contracts/src/capabilities/guards.d.ts

@@ -0,0 +1,4 @@
+import "../presentations/presentations.js";
+import "../operations/operation.js";
+import "./context.js";
+import "../events.js";

package/dist/contracts/src/capabilities/index.d.ts

@@ -1,2 +1,5 @@
 import { CapabilityKind, CapabilityMeta, CapabilityRef, CapabilityRequirement, CapabilitySpec, CapabilitySurface, CapabilitySurfaceRef } from "./capabilities.js";
+import "./validation.js";
+import "./context.js";
+import "./guards.js";
 import "./openbanking.js";

package/dist/contracts/src/capabilities/validation.d.ts

@@ -0,0 +1,4 @@
+import "./capabilities.js";
+import "../operations/registry.js";
+import "../presentations/index.js";
+import "../events.js";

package/dist/contracts/src/events.d.ts

@@ -1,21 +1,41 @@
 import { AnySchemaModel } from "../../schema/src/SchemaModel.js";
 import "../../schema/src/index.js";
+import { CapabilityRef } from "./capabilities/capabilities.js";
 import { DocId } from "./docs/registry.js";
 import { OwnerShipMeta } from "./ownership.js";
 import "./registry.js";
 
 //#region ../contracts/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;

package/dist/contracts/src/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","names":[],"sources":["../../../../contracts/src/events.ts"],"sourcesContent":[],"mappings":";;;;;;;UAKiB,aAAA,SAAsB,KAAK;;UAElC;AAFV;;;;;AASiB,UAAA,SAAS,CAAA,UAAW,cAAX,CAAA,CAAA;EAAW,IAAA,EAC7B,aAD6B;EAC7B;EAIG,GAAA,CAAA,EAAA,MAAA,EAAA;EAAC;WAAD"}
+{"version":3,"file":"events.d.ts","names":[],"sources":["../../../../contracts/src/events.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;UAiDiB,aAAA,SAAsB,KAAK;;UAElC;;;;;;;;;;;UAYO,oBAAoB;;QAE7B;;;;;eAKO;;;;;;;WAOJ"}

package/dist/contracts/src/experiments/spec.d.ts

@@ -1,13 +1,16 @@
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 import "../ownership.js";
 import "../policy/spec.js";
 import "../telemetry/spec.js";
 import "../registry.js";
 
 //#region ../contracts/src/experiments/spec.d.ts
-interface ExperimentRef {
-  key: string;
-  version?: string;
-}
+
+/**
+ * Reference to an experiment spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type ExperimentRef = OptionalVersionedSpecRef;
 //#endregion
 export { ExperimentRef };
 //# sourceMappingURL=spec.d.ts.map

package/dist/contracts/src/experiments/spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/experiments/spec.ts"],"sourcesContent":[],"mappings":";;;;;;UAOiB,aAAA;EAAA,GAAA,EAAA,MAAA"}
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/experiments/spec.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAaA;;;;KAAY,aAAA,GAAgB"}

package/dist/contracts/src/features/install.d.ts

@@ -1,6 +1,6 @@
 import "../presentations/presentations.js";
-import "../capabilities/index.js";
 import "../operations/registry.js";
+import "../presentations/index.js";
+import "../capabilities/index.js";
 import "./types.js";
-import "./registry.js";
-import "../presentations/index.js";
+import "./registry.js";

package/dist/contracts/src/features/types.d.ts

@@ -1,46 +1,40 @@
+import { 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 ../contracts/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;

package/dist/contracts/src/features/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../../../contracts/src/features/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;KAOY,iBAAA,GAAoB;UAEf,KAAA;;EAFL,GAAA,EAAA,MAAA;EAEK;EAOA,OAAA,EAAA,MAAQ;AAOzB;AAUiB,UAjBA,QAAA,CAiBW;EAQX;EAMA,GAAA,EAAA,MAAA;EACT;EAEO,OAAA,EAAA,MAAA;;AAIG,UA/BD,eAAA,CA+BC;EAEF;EAGD,GAAA,EAAA,MAAA;EACA;EAGY,OAAA,EAAA,MAAA;;;;;AAqBjB,UAnDO,WAAA,CAmDP;EAAO,GAAA,EAAA,MAAA;;;;;;UA3CA,OAAA;;;;;UAMA,iBAAA;QACT;;eAEO;;WAEJ;;kBAEO;;gBAEF;;;eAGD;eACA;;;;QAGY;UAAa;;;;;;;;;aAQ3B;;;;;;oBAOO;;cAGN;;UAGJ"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../../../contracts/src/features/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;KAQY,iBAAA,GAAoB;;;AAAhC;AAMA;AAMY,KANA,KAAA,GAAQ,gBAMG;AAMvB;AAMA;AAMA;AAGA;AACQ,KAtBI,QAAA,GAAW,gBAsBf;;;;;AAWO,KA3BH,eAAA,GAAkB,gBA2Bf;;;;;AAmBK,KAxCR,WAAA,GAAc,gBAwCN;;;;;KAlCR,OAAA,GAAU;;UAGL,iBAAA;QACT;;eAEO;;WAEJ;;kBAEO;;gBAEF;;;eAGD;eACA;;;;QAGY;UAAa;;;;;;;;;aAQ3B;;;;;;oBAOO;;cAGN;;UAGJ"}

package/dist/contracts/src/index.d.ts

@@ -1,4 +1,6 @@
 import "../../schema/src/index.js";
+import { OptionalVersionedSpecRef, VersionedSpecRef } from "./versioning/refs.js";
+import { CapabilityKind, CapabilityMeta, CapabilityRef, CapabilityRequirement, CapabilitySpec, CapabilitySurface, CapabilitySurfaceRef } from "./capabilities/capabilities.js";
 import { PresentationTarget } from "./presentations/presentations.js";
 import { DocId } from "./docs/registry.js";
 import "./docs/index.js";
@@ -6,16 +8,15 @@ import { Owner, OwnerShipMeta, OwnersEnum, Stability, StabilityEnum, Tag, TagsEn
 import "./registry-utils.js";
 import { PolicyRef } from "./policy/spec.js";
 import "./telemetry/index.js";
-import { CapabilityKind, CapabilityMeta, CapabilityRef, CapabilityRequirement, CapabilitySpec, CapabilitySurface, CapabilitySurfaceRef } from "./capabilities/capabilities.js";
-import "./capabilities/index.js";
-import { ExperimentRef } from "./experiments/spec.js";
 import { ResourceRefDescriptor } from "./resources.js";
 import { TestSpecRef } from "./tests/spec.js";
 import { EmitDecl, EmitDeclInline, EmitDeclRef, ImplementationRef, ImplementationType, OpKind, OperationSpec, OperationSpecMeta, TelemetryTrigger } from "./operations/operation.js";
-import "./install.js";
 import "./operations/index.js";
-import { DataViewRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FormRef, OpRef, PresentationRef } from "./features/types.js";
+import "./install.js";
 import "./presentations/index.js";
+import "./capabilities/index.js";
+import { ExperimentRef } from "./experiments/spec.js";
+import { DataViewRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FormRef, OpRef, PresentationRef } from "./features/types.js";
 import "./features/index.js";
 import "./data-views/index.js";
 import "./themes.js";

package/dist/contracts/src/install.d.ts

@@ -1,7 +1,7 @@
 import "../../schema/src/index.js";
 import "./resources.js";
-import "./operations/registry.js";
 import "./operations/index.js";
+import "./operations/registry.js";
 import "./types.js";
 import "./events.js";
 import "zod";

package/dist/contracts/src/integrations/openbanking/contracts/accounts.d.ts

@@ -1,4 +1,4 @@
 import "../../../../../schema/src/index.js";
-import "../../../operations/registry.js";
 import "../../../operations/index.js";
+import "../../../operations/registry.js";
 import "../../../index.js";

package/dist/contracts/src/integrations/openbanking/contracts/balances.d.ts

@@ -1,4 +1,4 @@
 import "../../../../../schema/src/index.js";
-import "../../../operations/registry.js";
 import "../../../operations/index.js";
+import "../../../operations/registry.js";
 import "../../../index.js";

package/dist/contracts/src/integrations/openbanking/contracts/transactions.d.ts

@@ -1,4 +1,4 @@
 import "../../../../../schema/src/index.js";
-import "../../../operations/registry.js";
 import "../../../operations/index.js";
+import "../../../operations/registry.js";
 import "../../../index.js";

package/dist/contracts/src/integrations/operations.d.ts

@@ -1,4 +1,4 @@
 import "../../../schema/src/index.js";
-import "../operations/registry.js";
 import "../operations/index.js";
+import "../operations/registry.js";
 import "../index.js";

package/dist/contracts/src/knowledge/operations.d.ts

@@ -1,4 +1,4 @@
 import "../../../schema/src/index.js";
-import "../operations/registry.js";
 import "../operations/index.js";
+import "../operations/registry.js";
 import "../index.js";

package/dist/contracts/src/llm/exporters.d.ts

@@ -1,6 +1,6 @@
 import "../../../schema/src/index.js";
-import "../operations/registry.js";
 import "../operations/index.js";
+import "../operations/registry.js";
 import "../presentations/index.js";
 import "../features/index.js";
 import "../events.js";

package/dist/contracts/src/operations/operation.d.ts

@@ -1,5 +1,6 @@
 import { AnySchemaModel } from "../../../schema/src/SchemaModel.js";
 import "../../../schema/src/index.js";
+import { CapabilityRef } from "../capabilities/capabilities.js";
 import { OwnerShipMeta } from "../ownership.js";
 import { PolicyRef } from "../policy/spec.js";
 import { ResourceRefDescriptor } from "../resources.js";
@@ -70,6 +71,11 @@ interface OperationSpecMeta extends OwnerShipMeta {
  */
 interface OperationSpec<Input extends AnySchemaModel, Output extends AnySchemaModel | ResourceRefDescriptor<boolean>, Events extends readonly EmitDecl[] | undefined = readonly EmitDecl[] | undefined> {
   meta: OperationSpecMeta;
+  /**
+   * Optional reference to the capability that provides this operation.
+   * Used for bidirectional linking between capabilities and operations.
+   */
+  capability?: CapabilityRef;
   io: {
     /** Zod schema for input body payload */
     input: Input | null;

package/dist/contracts/src/operations/operation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operation.d.ts","names":[],"sources":["../../../../../contracts/src/operations/operation.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAmBA;AAaA;AAUA;AAKiB,KAjCL,MAAA,GAiCmB,SAAA,GAAA,OAIpB;AAMX;AAGA;AASA;AAeiB,KAjEL,kBAAA,GAiEkB,SAAA,GAAA,WAAA,GAAA,MAAA,GAAA,MAAA,GAAA,SAAA,GAAA,MAAA,GAAA,OAAA;;;;;AAIf,UAxDE,iBAAA,CAwDF;EAGP;EAIG,IAAA,EAAA,MAAA;EAGE;EAGD,IAAA,EAjEJ,kBAiEI;EAGE;EAGF,WAAA,CAAA,EAAA,MAAA;;AA2BG,UA5FE,WAAA,CA4FF;EAKA,GAAA,EAhGR,SAgGQ,CAhGE,cAgGF,CAAA,CAAA,MAAA,CAAA;EAMH,IAAA,EAAA,MAAA;;AASE,UA3GG,cAAA,CA2GH;EAGJ,GAAA,EAAA,MAAA;EAsCU,OAAA,EAAA,MAAA;EAAiB,IAAA,EAAA,MAAA;WAhJ1B;;;;;;KAMC,QAAA,GAAW,cAAc;UAGpB,gBAAA;;;;;;;;;QAMT;;UAGS,iBAAA,SAA0B;QACnC;;;;;;;;;;;;;UAcS,4BACD,+BACC,iBAAiB,wDACR,kCACX;QAGP;;;WAIG;;aAGE;;YAGD;;cAGE;;YAGF;;aAEC;;;;;;;;;;;;;;;;;;;;;;;;eAyBE;;;;;eAKA;;;;;YAMH;;;;;;;cAQE;cACA;;UAGJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAsCU"}
+{"version":3,"file":"operation.d.ts","names":[],"sources":["../../../../../contracts/src/operations/operation.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAoBA;AAaA;AAUA;AAKiB,KAjCL,MAAA,GAiCmB,SAAA,GAAA,OAIpB;AAMX;AAGA;AASA;AAeiB,KAjEL,kBAAA,GAiEkB,SAAA,GAAA,WAAA,GAAA,MAAA,GAAA,MAAA,GAAA,SAAA,GAAA,MAAA,GAAA,OAAA;;;;;AAIf,UAxDE,iBAAA,CAwDF;EAGP;EAMO,IAAA,EAAA,MAAA;EAIJ;EAGE,IAAA,EApEL,kBAoEK;EAGD;EAGE,WAAA,CAAA,EAAA,MAAA;;AAKD,UAzEI,WAAA,CAyEJ;EAyBE,GAAA,EAjGR,SAiGQ,CAjGE,cAiGF,CAAA,CAAA,MAAA,CAAA;EAKA,IAAA,EAAA,MAAA;;AAcD,UAhHG,cAAA,CAgHH;EACA,GAAA,EAAA,MAAA;EAGJ,OAAA,EAAA,MAAA;EAsCU,IAAA,EAAA,MAAA;EAAiB,OAAA,EAtJ1B,cAsJ0B;;;;;;KAhJzB,QAAA,GAAW,cAAc;UAGpB,gBAAA;;;;;;;;;QAMT;;UAGS,iBAAA,SAA0B;QACnC;;;;;;;;;;;;;UAcS,4BACD,+BACC,iBAAiB,wDACR,kCACX;QAGP;;;;;eAMO;;;WAIJ;;aAGE;;YAGD;;cAGE;;YAGF;;aAEC;;;;;;;;;;;;;;;;;;;;;;;;eAyBE;;;;;eAKA;;;;;YAMH;;;;;;;cAQE;cACA;;UAGJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAsCU"}

package/dist/contracts/src/ownership.d.ts

@@ -2,58 +2,161 @@ import { DocId } from "./docs/registry.js";
 import "./docs/index.js";
 
 //#region ../contracts/src/ownership.d.ts
+
+/**
+ * Lifecycle stability stages for specs.
+ *
+ * Specs progress through these stages as they mature:
+ * - `idea`: Initial concept, not implemented
+ * - `in_creation`: Currently being built
+ * - `experimental`: Working but may change significantly
+ * - `beta`: Feature-complete, seeking feedback
+ * - `stable`: Production-ready, breaking changes require major version bump
+ * - `deprecated`: Scheduled for removal, use alternatives
+ */
 declare const StabilityEnum: {
+  /** Initial concept, not yet implemented. */
   readonly Idea: "idea";
+  /** Currently being built, not ready for use. */
   readonly InCreation: "in_creation";
+  /** Working but unstable, may change significantly. */
   readonly Experimental: "experimental";
+  /** Feature-complete, seeking feedback before stabilization. */
   readonly Beta: "beta";
+  /** Production-ready, follows semantic versioning. */
   readonly Stable: "stable";
+  /** Scheduled for removal, use alternatives. */
   readonly Deprecated: "deprecated";
 };
+/** Stability level for a spec's lifecycle stage. */
 type Stability = (typeof StabilityEnum)[keyof typeof StabilityEnum];
+/**
+ * Curated owner identifiers for business/product ownership.
+ *
+ * Used for CODEOWNERS, on-call routing, and approval workflows.
+ * Custom owner strings are also allowed for flexibility.
+ */
 declare const OwnersEnum: {
+  /** Core platform team. */
   readonly PlatformCore: "platform.core";
+  /** Sigil/auth team. */
   readonly PlatformSigil: "platform.sigil";
+  /** Marketplace team. */
   readonly PlatformMarketplace: "platform.marketplace";
+  /** Messaging/notifications team. */
   readonly PlatformMessaging: "platform.messaging";
+  /** Content/CMS team. */
   readonly PlatformContent: "platform.content";
+  /** Feature flags team. */
   readonly PlatformFeatureFlags: "platform.featureflags";
+  /** Finance/billing team. */
   readonly PlatformFinance: "platform.finance";
 };
+/**
+ * Owner identifier for a spec.
+ * Can be a predefined OwnersEnum value or any custom string.
+ */
 type Owner = (typeof OwnersEnum)[keyof typeof OwnersEnum] | (string & {});
+/**
+ * Common tags for categorizing specs.
+ *
+ * Used for search, grouping, and documentation navigation.
+ * Custom tag strings are also allowed for flexibility.
+ */
 declare const TagsEnum: {
+  /** Spots/locations domain. */
   readonly Spots: "spots";
+  /** Collectivity/community domain. */
   readonly Collectivity: "collectivity";
+  /** Marketplace domain. */
   readonly Marketplace: "marketplace";
+  /** Seller-related features. */
   readonly Sellers: "sellers";
+  /** Authentication features. */
   readonly Auth: "auth";
+  /** Login flows. */
   readonly Login: "login";
+  /** Signup flows. */
   readonly Signup: "signup";
+  /** Onboarding/guides. */
   readonly Guide: "guide";
+  /** Documentation. */
   readonly Docs: "docs";
+  /** Internationalization. */
   readonly I18n: "i18n";
+  /** Incident management. */
   readonly Incident: "incident";
+  /** Automation/workflows. */
   readonly Automation: "automation";
+  /** Code hygiene/maintenance. */
   readonly Hygiene: "hygiene";
 };
+/**
+ * Tag for categorizing a spec.
+ * Can be a predefined TagsEnum value or any custom string.
+ */
 type Tag = (typeof TagsEnum)[keyof typeof TagsEnum] | (string & {});
+/**
+ * Common metadata interface for all ContractSpec specifications.
+ *
+ * Every spec type (operations, events, presentations, etc.) extends this
+ * interface to provide consistent ownership, versioning, and discoverability.
+ *
+ * @example
+ * ```typescript
+ * const meta: OwnerShipMeta = {
+ *   key: 'auth.login',
+ *   version: '1.0.0',
+ *   description: 'Authenticates a user with email and password',
+ *   stability: StabilityEnum.Stable,
+ *   owners: [OwnersEnum.PlatformSigil],
+ *   tags: [TagsEnum.Auth, TagsEnum.Login],
+ * };
+ * ```
+ */
 interface OwnerShipMeta {
-  /** Breaking changes => bump version */
+  /**
+   * Semantic version string (e.g., "1.0.0").
+   * Bump for breaking changes according to semver rules.
+   */
   version: string;
-  /** Fully-qualified spec key (e.g., "sigil.beginSignup") */
+  /**
+   * Fully-qualified spec key (e.g., "sigil.beginSignup", "user.created").
+   * Must be unique within the spec type.
+   */
   key: string;
-  /** Human-friendly spec title (e.g., "Signup begin") */
+  /**
+   * Human-friendly title (e.g., "Begin Signup").
+   * Used in documentation and UI.
+   */
   title?: string;
-  /** Short human-friendly summary */
+  /**
+   * Short human-friendly summary of what this spec does.
+   * Should be concise (1-2 sentences).
+   */
   description: string;
+  /**
+   * Business domain this spec belongs to (e.g., "auth", "marketplace").
+   * Used for grouping and discovery.
+   */
   domain?: string;
-  /** Lifecycle marker for comms & tooling */
+  /**
+   * Lifecycle stability marker.
+   * Indicates maturity level and change expectations.
+   */
   stability: Stability;
-  /** Owners for CODEOWNERS / on-call / approvals */
+  /**
+   * Team/individual owners responsible for this spec.
+   * Used for CODEOWNERS, on-call routing, and approvals.
+   */
   owners: Owner[];
-  /** Search tags, grouping, docs navigation */
+  /**
+   * Tags for search, grouping, and documentation navigation.
+   */
   tags: Tag[];
-  /** Doc block(s) for this operation. */
+  /**
+   * Associated DocBlock identifiers for documentation linkage.
+   */
   docId?: DocId[];
 }
 //#endregion

package/dist/contracts/src/ownership.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ownership.d.ts","names":[],"sources":["../../../../contracts/src/ownership.ts"],"sourcesContent":[],"mappings":";;;;cAIa;;;EAAA,SAAA,YAOH,EAAA,cAAA;EACE,SAAA,IAAS,EAAA,MAAA;EAGR,SAAA,MAQH,EAAA,QAAA;EACE,SAAK,UAAA,EACL,YAAyB;AAMrC,CAAA;AAeY,KAlCA,SAAA,GAkCc,CAAA,OAlCM,aAkCyB,CAAA,CAAA,MAAA,OAlCG,aAkCH,CAAA;AAIxC,cAnCJ,UAmCiB,EAAA;EAWjB,SAAA,YAAA,EAAA,eAAA;EAEH,SAAA,aAAA,EAAA,gBAAA;EAEF,SAAA,mBAAA,EAAA,sBAAA;EAGE,SAAA,iBAAA,EAAA,oBAAA;EAAK,SAAA,eAAA,EAAA,kBAAA;;;;KA5CH,KAAA,WACA,yBAAyB;cAMxB;;;;;;;;;;;;;;;KAeD,GAAA,WAAc,uBAAuB;UAIhC,aAAA;;;;;;;;;;;aAWJ;;UAEH;;QAEF;;UAGE"}
+{"version":3,"file":"ownership.d.ts","names":[],"sources":["../../../../contracts/src/ownership.ts"],"sourcesContent":[],"mappings":";;;;;AA6HA;AA2BA;;;;;;;;;;cA9Ha;;;;;;;;;;;;;;;KAgBD,SAAA,WAAoB,4BAA4B;;;;;;;cAY/C;;;;;;;;;;;;;;;;;;;;KAqBD,KAAA,WACA,yBAAyB;;;;;;;cAgBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAiCD,GAAA,WAAc,uBAAuB;;;;;;;;;;;;;;;;;;;UA2BhC,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAmCJ;;;;;UAMH;;;;QAKF;;;;UAKE"}

package/dist/contracts/src/policy/guards.d.ts

@@ -0,0 +1 @@
+import "../operations/operation.js";

package/dist/contracts/src/policy/index.d.ts

@@ -1,4 +1,6 @@
 import { PolicyRef } from "./spec.js";
 import "./registry.js";
 import "./engine.js";
-import "./opa-adapter.js";
+import "./opa-adapter.js";
+import "./guards.js";
+import "./validation.js";

package/dist/contracts/src/policy/spec.d.ts

@@ -1,11 +1,13 @@
+import { VersionedSpecRef } from "../versioning/refs.js";
 import "../ownership.js";
 
 //#region ../contracts/src/policy/spec.d.ts
 
-interface PolicyRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a policy spec.
+ * Uses key and version to identify a specific policy.
+ */
+type PolicyRef = VersionedSpecRef;
 //#endregion
 export { PolicyRef };
 //# sourceMappingURL=spec.d.ts.map

package/dist/contracts/src/policy/spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/policy/spec.ts"],"sourcesContent":[],"mappings":";;;;UAmHiB,SAAA"}
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/policy/spec.ts"],"sourcesContent":[],"mappings":";;;;;;;;;KAyHY,SAAA,GAAY"}

package/dist/contracts/src/policy/validation.d.ts

@@ -0,0 +1,3 @@
+import "./spec.js";
+import "../operations/registry.js";
+import "./registry.js";

package/dist/contracts/src/presentations/presentations.d.ts

@@ -1,4 +1,5 @@
 import "../../../schema/src/index.js";
+import "../capabilities/capabilities.js";
 import "../ownership.js";
 
 //#region ../contracts/src/presentations/presentations.d.ts

package/dist/contracts/src/presentations/presentations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presentations.d.ts","names":[],"sources":["../../../../../contracts/src/presentations/presentations.ts"],"sourcesContent":[],"mappings":";;;;;AAKY,KAAA,kBAAA,GAAkB,OAAA,GAAA,UAAA,GAAA,kBAAA,GAAA,iBAAA"}
+{"version":3,"file":"presentations.d.ts","names":[],"sources":["../../../../../contracts/src/presentations/presentations.ts"],"sourcesContent":[],"mappings":";;;;;;AAMY,KAAA,kBAAA,GAAkB,OAAA,GAAA,UAAA,GAAA,kBAAA,GAAA,iBAAA"}

package/dist/contracts/src/server/mcp/createMcpServer.d.ts

@@ -1,4 +1,5 @@
 import "../../resources.js";
 import "../../operations/registry.js";
 import "../../promptRegistry.js";
-import "./mcpTypes.js";
+import "./mcpTypes.js";
+import "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/contracts/src/tests/spec.d.ts

@@ -1,11 +1,13 @@
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 import "../ownership.js";
 
 //#region ../contracts/src/tests/spec.d.ts
 
-interface TestSpecRef {
-  key: string;
-  version?: string;
-}
+/**
+ * Reference to a test spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type TestSpecRef = OptionalVersionedSpecRef;
 //#endregion
 export { TestSpecRef };
 //# sourceMappingURL=spec.d.ts.map

package/dist/contracts/src/tests/spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/tests/spec.ts"],"sourcesContent":[],"mappings":";;;;UAiFiB,WAAA"}
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/tests/spec.ts"],"sourcesContent":[],"mappings":";;;;;;;;;KAwFY,WAAA,GAAc"}

package/dist/contracts/src/versioning/refs.d.ts

@@ -0,0 +1,47 @@
+//#region ../contracts/src/versioning/refs.d.ts
+/**
+ * Base reference types for ContractSpec versioning.
+ *
+ * Provides canonical reference types for linking between specs.
+ * Domain-specific refs (OpRef, EventRef, etc.) should alias these
+ * base types for consistency and maintainability.
+ *
+ * @module versioning/refs
+ */
+/**
+ * Base reference type for versioned specs.
+ * Used to reference any spec by its key and version.
+ *
+ * @example
+ * ```typescript
+ * const opRef: VersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
+ * ```
+ */
+interface VersionedSpecRef {
+  /** Unique key identifying the spec (e.g., "auth.login", "user.created"). */
+  key: string;
+  /** Semantic version of the spec (e.g., "1.0.0", "2.1.0"). */
+  version: string;
+}
+/**
+ * Base reference type for specs with optional version.
+ * When version is omitted, typically refers to the latest version.
+ *
+ * @example
+ * ```typescript
+ * // Reference to latest version
+ * const latestRef: OptionalVersionedSpecRef = { key: 'auth.login' };
+ *
+ * // Reference to specific version
+ * const specificRef: OptionalVersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
+ * ```
+ */
+interface OptionalVersionedSpecRef {
+  /** Unique key identifying the spec. */
+  key: string;
+  /** Optional semantic version. When omitted, refers to the latest version. */
+  version?: string;
+}
+//#endregion
+export { OptionalVersionedSpecRef, VersionedSpecRef };
+//# sourceMappingURL=refs.d.ts.map

package/dist/contracts/src/versioning/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","names":[],"sources":["../../../../../contracts/src/versioning/refs.ts"],"sourcesContent":[],"mappings":";;AAuBA;AAoBA;;;;;;;;;;;;;;;;UApBiB,gBAAA;;;;;;;;;;;;;;;;;;;UAoBA,wBAAA"}

package/dist/contracts/src/workflow/context.d.ts

@@ -0,0 +1,2 @@
+import "./spec.js";
+import "./state.js";

package/dist/contracts/src/workflow/index.d.ts

@@ -3,4 +3,6 @@ import "./spec.js";
 import "./validation.js";
 import "./state.js";
 import "./runner.js";
-import "./adapters/index.js";
+import "./adapters/index.js";
+import "./context.js";
+import "./sla-monitor.js";

package/dist/contracts/src/workflow/sla-monitor.d.ts

@@ -0,0 +1,2 @@
+import "./spec.js";
+import "./state.js";

package/dist/contracts/src/workflow/validation.d.ts

@@ -1,3 +1,5 @@
+import "../capabilities/capabilities.js";
 import "../operations/registry.js";
 import "./spec.js";
+import "../events.js";
 import "../forms/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.feature-flags",
-  "version": "1.49.0",
+  "version": "1.51.0",
   "description": "Feature flags and experiments module for ContractSpec applications",
   "keywords": [
     "contractspec",
@@ -24,13 +24,13 @@
     "lint:check": "eslint src"
   },
   "dependencies": {
-    "@contractspec/lib.schema": "1.49.0",
-    "@contractspec/lib.contracts": "1.49.0",
+    "@contractspec/lib.schema": "1.51.0",
+    "@contractspec/lib.contracts": "1.51.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "1.49.0",
-    "@contractspec/tool.tsdown": "1.49.0",
+    "@contractspec/tool.typescript": "1.51.0",
+    "@contractspec/tool.tsdown": "1.51.0",
     "typescript": "^5.9.3"
   },
   "exports": {